Documentando plugins e temas do WordPress

A documentação é algo que geralmente só é apreciado quando há um problema e você precisa de respostas rapidamente. Neste artigo, veremos os motivos pelos quais escrever documentação para seus ativos do WordPress é importante para sua prática como desenvolvedor do WordPress e a qualidade dos temas e plugins que você envia.

Por que a documentação é importante?

Manter um conjunto atualizado de documentação sobre seus projetos, ativos ou produtos é importante por vários motivos.

Primeiro, é uma experiência comum olhar para algo que você fez 2 meses atrás e não tocou desde então, e não ter ideia do que isso significa. Quando você o desenvolve, você tem tudo dentro de sua cabeça, mas esse entendimento não estará lá no futuro. Portanto, usar comentários de código embutido ou escrever notas de texto simples no Markdown, ajuda bastante a salvar seu eu futuro da confusão.

Em segundo lugar, manter seus ativos documentados é útil para outros desenvolvedores do WordPress. E isso faz sentido mesmo se você for um freelancer solitário (você é obrigado a colaborar com outras pessoas em algum momento). Eles precisarão usar esses ativos ou serão solicitados a mantê-los e/ou atualizá-los. É muito frustrante ter que usar código não documentado escrito por outra pessoa, que não está por perto para fornecer suporte ou explicar algumas partes difíceis.

Por fim, a documentação acrescenta aquela aparência “polida” aos seus produtos e seus clientes vão adorar você ainda mais.

5 princípios para uma documentação eficaz

A redação técnica é uma disciplina por si só e é usada para comunicar informações técnicas de maneira clara e inequívoca. (Não se limitando apenas aos computadores, advogados e médicos, por exemplo, também usam sua própria linguagem técnica). Por isso, um documento que é considerado redação técnica costuma seguir um certo estilo e obedecer a um conjunto de regras.

Vamos passar pelos 5 mais importantes para que você possa escrever uma documentação eficaz para seus produtos!

• Prefira usar menos palavras do que você normalmente usaria em sua escrita: Cada palavra deve ter um propósito. Seja direto e simples. A documentação geralmente é procurada quando uma pessoa está com problemas e deseja encontrar rapidamente uma solução. Por exemplo, uma frase como “A falha ao destruir o objeto Q introduzirá vazamentos de memória” é preferível do que “A falha ao destruir o objeto Q causará a introdução de vazamentos de memória”.
• Prefira usar voz ativa em vez de passiva: “ Clique no botão no canto superior direito” em vez de “O botão no canto superior direito precisa ser clicado ”. Usar uma voz ativa elimina quaisquer ambiguidades sobre quem faz o quê. A voz passiva é usada apenas quando você precisa se concentrar no objeto, e não no assunto (por exemplo, a Plataforma Pressidium é construída com segurança em mente ) .
• Use linguagem descritiva quando precisar descrever conceitos e imperativo quando precisar descrever um procedimento passo a passo (como tutoriais).
• Use listas de marcadores quando precisar listar coisas que não têm ordem e listas numeradas quando a ordem dos pontos for significativa.
• Certifique-se de que você mesmo testou as instruções antes de apresentá-las!

Documentando plugins do WordPress

Os plugins do WordPress são como qualquer outro software. Eles fornecem uma certa funcionalidade, exigem instalação e, às vezes, também solução de problemas. Por mais simples que sejam, é sempre uma boa ideia fornecer uma quantidade adequada de documentação, porque nem todos os usuários compartilham o mesmo conhecimento técnico.

Hospede seu site com a Pressidium

GARANTIA DE DEVOLUÇÃO DO DINHEIRO DE 60 DIAS

VEJA NOSSOS PLANOS

Publicar seu plugin WordPress no wordpress.org fornecerá um local para colocar instruções de instalação, capturas de tela, FAQ e até mesmo um Changelog! Preenchê-los com informações úteis e de qualidade é fundamental para tornar seu plugin mais popular:

• Escreva uma descrição atraente e útil que fará com que o usuário baixe seu plugin e visite seu site.
• Adicione capturas de tela comentadas explicando cada item de configuração do seu plug-in, além daquelas que mostram a aparência do plug-in no navegador.
• Coloque perguntas no FAQ que não sejam banais. Uma boa maneira de descobrir casos extremos estranhos é pedir a um amigo que não tenha experiência com computadores para usar seu plug-in.
• Tenha um Changelog atualizado e bem escrito. Frases concisas e enigmáticas são um grande não-não e mostram que você realmente não se importa com seus usuários.
• Certifique-se de que o código do seu plugin esteja bem comentado e siga as melhores práticas de software e padrões oficiais de codificação.

Se você está preso e precisa de alguma inspiração, faça uma pequena pesquisa e veja como o texto é escrito em plugins populares que possuem centenas de milhares de instalações, em comparação com os menos usados.

Documentando temas do WordPress

Documentar temas do WordPress é uma questão completamente diferente. O problema mais comum com os temas do WordPress é não saber qual seção corresponde a qual elemento visual. Nem todo mundo é fluente em CSS:

• Crie uma hierarquia de todas as seções do seu CSS, com as descrições correspondentes.
• Para cada seção, adicione uma captura de tela anotada detalhando cada funcionalidade, juntamente com um pequeno exemplo. Não se esqueça de usar voz ativa e linguagem imperativa, ao mostrar como fazer algo que exija que o usuário siga instruções.
• Use uma ferramenta como css_doc para ajudá-lo. Isso gera um estilo de documentação JavaDoc e pode ser publicado.
• Às vezes, os comentários de código não são suficientes e você precisa criar um documento de Guia de Estilo para o seu tema CSS. Os documentos do guia de estilo descrevem como os elementos precisam ser e em quais casos eles precisam ser usados. Eles reforçam a consistência e também facilitam a colaboração. Veja este exemplo do Google.
• Use uma estrutura CSS como Blueprint CSS. Isso ajudará você no desenvolvimento, fornecendo um conjunto de ferramentas, como uma grade personalizável, tipografia padrão que funciona, redefinição de CSS do navegador e muito mais.
• Novamente, não se esqueça de consultar os padrões oficiais de codificação CSS do WordPress.