Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. WordPress

Documentando Sua Framework para Temas de WordPress

by
Difficulty:IntermediateLength:MediumLanguages:
This post is part of a series called How Theme Frameworks Actually Work.
Releasing your WordPress Theme Framework

Portuguese (Português) translation by Erick Patrick (you can also view the original English article)

Bem... Agora, você tem uma framework para temas de WordPress. Meus parabéns! O esforço que teve no desenvolvimento dela será recompensado mais para frente e tornará seu processo de desenvolvimento muito mais eficiente e direto.

Mas, você precisa fazer uma última coisa antes de terminar: documentar sua framework. No mínimo, precisa garantir bons comentários pelo seu código, mas também é interessante que crie outra documentação, de modo que mantenha o controle sobre os arquivos, funções e filtros que fazem parte da API da sua framework.

Os pontos que cobrirei serão:

  • Comentários
  • Criação do arquivo README
  • Uso de ferramentas de documentação automática
  • Criação de wikis
  • Criação de websites
  • Criação de tutoriais ou gravação de vídeos

Perceba que mencionarei algumas ferramentas de documentação, porém, esse artigo não serve como recomendação, já que eu mesmo não as usei em minha própria framework, então, é necessário que tome sua própria opinião sobre elas adequarem-se ou não.

Escrevendo Comentários com Qualidade

Os comentários são particularmente importantes quando outros desenvolvedores trabalharem com seu código (por exemplo, se você trabalhar em equipe ou caso lance sua framework para o público). Mas, não é só nesse momento. Quando estiver trabalhando por conta própria, é bem fácil esquecer o que, exatamente, um trecho de código faz. Um exemplo é quando você precisa editar um certo arquivo um ano depois.

Imagine que usou sua framework para construir o site de um cliente. Dois anos depois, o site apresenta um problema às 17h30 de uma sexta-feira. Bons comentários podem fazer a diferença entre ajustar o problema rapidamente, ir para casa e descansar no fim-de-semana, e ter de vasculhar centenhas de linhas de código tentando encontrar o erro e perder sua preciosa noite de sexta.

Eis algumas dicas para bons comentários:

  • Use comentários no inicio do arquivo, explicando o que ele faz. Por exemplo, nos arquivos de modelo, inclua uma nota sobre os dados que ele mostra e quaisquer customizações que fez no loop ou outras partes do arquivo. E em arquivos de plugins, adicione uma nota em relação a sua funcionalidade. Por exemplo, o comentário abaixo diz aos usuários o nome do arquivo do modelo, o que ele faz, a qual tema ele pertence (@package), e em qual versão do tema ele foi disponibilizado (@since). Você pode usar um sistema parecido em arquivos de plugins.
  • Use comentários para demarcar seções do seu código, não somente em folhas de estilos, mas, também, em seus arquivos de modelo e de funções.
  • Comente tudo que não for padrão.
  • Comente qualquer coisa que demorou um pouco mais para ser criado - use comentários detalhados para quando retornar, não ter de pensar muito sobre o problema de novo.
  • Comente qualquer coisa que você saiba que serão trabalhadas por outra pessoa - por exemplo, se seus arquivos de modelo contém scripts que outras pessoas aperfeiçoarão, adicione comentários explicando onde eles estarão no site.
  • Use palavras em seu comentários que podem ser usadas para buscas posteriores - então, não abrevie e use termos que outras pessoas entenderão.
  • Toda vez que remover algum código através do uso de comentários, deixe um comentário explicando isso. Dessa forma, se esquecer de remover tal código após terminar o desenvolvimento, ou se quiser adicioná-lo novamente, saberá o que aconteceu e o que fazer.
  • Em dúvida, adicione um comentário!

Criação de um Arquivo README

O arquivo readme.txt é o próximo passo após os comentários. É um arquivo único, que você inclui em seu tema, contendo informações sobre o mesmo.

O conjunto de códigos que acompanha essa série contem um simples arquivo readme.txt:

Se você quiser tornar seu arquivo readme mais amigável ao usuário, seria interessante transformá-lo em um arquivo readme.html, o que permitirá o usuário abri-lo em um navegador. Além disso, você pode usar CSS para aprimorar seu arquivo readme, tornando-o mais fácil de ler.

Se você quiser lançar seu tema através do repositório de temas do WordPress,espera-se que você proveja um arquivo readme.txt como mínimo em documentação. Cobrirei isso em mais detalhes no tutorial final dessa série, em "Lançando seu Framework para Temas.

Uso de Ferramentas de Documentação Automática

Se você planeja continuar desenvolvendo sua framework e não quer gastar muito tempo escrevendo documentação manualmente para cada nova funcionalidade, uma ferramenta de documentação automática pode ser a resposta.

A maioria delas envolve o uso de tags e sintaxes específicas para permitir que o sistema identifique o local para geração da documentação. Exemplos incluem:

Se quiser utilizar uma dessas ferramentas, é interessante gastar algum tempo identificando qual delas é a melhor antes de começar a usá-la, uma vez que é improvável transferir sua documentação de uma para outra.

Mas, uma vez entendido o funcionamento do sistema e como prepará-lo, uma ferramenta automática como essas pode economizar um bom tempo e evitar buracos na sua documentação, uma vez que estará muito mais ocupado criando código que atualizando a documentação.

Criação de Wiki ou Website

Essa opção dará mais trabalho e só vale a pena se perceber que sua framework está crescendo com o tempo e aumentando o número de usuários. Todas as maiores frameworks de temas tem seus próprios sites com documentação, disponíveis gratuitamente ou somente para membros.

O site que dá suporte a sua framework pode fazer parte da sua estratégia de monetização - a framework de temas hybrid, por exemplo, é gratuita, mas a documentação e o suporte só estão disponíveis através de inscrição paga no site da mesma.

Alternativamente, se estiver lançando sua framework como um produto premium, você pode requisitar login dos usuários para que possam ler a documentação, ou pode tornar sua documentaçao pública na esperança de encorajar mais alguém a adquirí-la.

Se sua framework é completamente grátis, talvez queira criar um site gratuito com documentação, como é o caso da framework Wonderflux:

Por outro lado, talvez prefira criar uma wiki, que tem a vantagem de permitir que os usuários contribuam para a documentação. Isso pode levar mais tempo para configurar que um site, na maioria dos casos, mas pode ser uma ferramenta valiosa para a comunidade que usa sua framework. Você pode criar uma wiki usando um plugin para o site WordPress da sua framework.

Criação de Tutoriais ou Gravação de Vídeos

Tutoriais podem ajudar novos usuários, principalmente aqueles que não sabem programar, ajudando a lidar com sua framework de forma mais rápida que a documentação padrão. Vídeos vão além, provendo um guia visual fácil, além de serem uma ótima ferramenta de marketing.

A framework Genesis tem um belo conjunto de tutoriais para seus usuários. Eles estão disponíveis apenas para inscritos pagantes:

Minha própria framework Edupress tem vários tutoriais em vídeo, os quais criei para ajudar os usuários dos mais variados níveis de experiência em computadores e/ou WordPress:

Eles estão disponíveis tanto no site público quanto no painel administrativo do usuário, podendo ser facilmente acessados enquanto os usuários trabalham com a framework. Se criar documentação, tutoriais ou vídeos para sua framework, é bom inserir uma tela no painel administrativo com detalhes para eles.

Entretanto, criar tutoriais ou vídeos demanda muito tempo e dá bastante trabalho para fazer do jeito certo: tutoriais mal escritos ou vídeos mal produzidos passarão uma má impressão da sua framework e talvez causem mais prejuízo que se fosse uma documentação mais simples.

Conclusão

Independente de quem usar sua framework para temas, é necessário algum tipo de documentação. Mesmo que você tenha desenvolvido a framework para você e sua equipe, ou para lançar ao mundo, você precisa registrar alguma informação relacionada a estruturação dos arquivos e da API.

As opções que discutimos acima vão dos mais simples comentários aos vídeos, que são mais complexos, abordando várias coisas entre esses dois extremos. O que você decidirá só depende das necessidades dos seus usuários e, talvez, mude com o tempo, dependendo do crescimento da sua base de usuários e das necessidades deles.

Seja o primeiro a saber sobre novas traduções–siga @tutsplus_pt no Twitter!

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.