Documentação do produto para profissionais do WordPress

Publicados: 2017-07-28

A documentação do produto geralmente é vista como inconsequente, que você pode cortar custos. Não é visto como algo que possa agregar valor ao cliente, ou como algo que possa afetar áreas-chave de negócios, como receita e marketing. É verdade que, como profissional do WordPress, você não precisará escrever documentação da mesma maneira que a Atlassian ou a Cisco. Normalmente, quando as pessoas pensam em “documentação”, elas evocam imagens de guias de usuário grossos e impressos, indexados em ordem alfabética em uma prateleira muito grande que ninguém nunca lê.

Mas isso mudou:

Com o advento do Agile e do DevOps, o envio de software se tornou mais rápido e o ciclo de desenvolvimento também se tornou mais dinâmico. E, como resultado, a documentação agora reflete o estado atual na versão mais recente, em vez de ser algo estático escrito no papel para sempre. A documentação é integrada ao ciclo de desenvolvimento e é atualizada com a mesma frequência que o software.

Por que os profissionais do WordPress devem se preocupar com a documentação do produto?

Documentação útil e atualizada não apenas facilita a vida de seus usuários, mas também adiciona um nível de polimento que se torna um ativo de marketing como nenhum outro. Por outro lado, a má documentação tem um impacto negativo. Você provavelmente já passou por isso: você teve um problema para o qual estava se esforçando para encontrar a solução na documentação e, quando não encontrou, acabou frustrado (e provavelmente com raiva). Só piora se você estiver pagando pelo produto.

Se você estiver trabalhando em uma agência WordPress, fornecer documentação em todas as áreas de um projeto, desde o design inicial até os ativos, adicionará um nível de profissionalismo mostrando que:

Você presta atenção aos detalhes.
Você se preocupa com seu cliente o suficiente para ir além.
Você é transparente e confiante sobre suas decisões de design e projeto técnico.

Mike Puterbaugh, vice-presidente de marketing da MindTouch, escreveu um artigo do Mashable descrevendo os 5 motivos pelos quais a documentação do seu produto é um ativo de marketing. Concluiu com o seguinte:

Não é um empreendimento sexy, mas você ganhará o respeito de seus colegas, uma gestão mais eficaz da empresa e uma equipe mais colaborativa. Porque não se trata deste trimestre ou deste ano, mas sim de afetar a vantagem competitiva e o crescimento de longo prazo.

Agora que estabelecemos motivação suficiente, vamos:

Explore os diferentes tipos de documentação do produto que são relevantes para o WordPress.
Discuta as necessidades de cada tipo de documentação e ofereça conselhos práticos.
Ofereça algumas orientações iniciais sobre como planejar e colaborar na documentação do produto. Especialmente se você estiver trabalhando em uma agência WordPress.

Tipos de documentação do produto WordPress

Um produto WordPress não é apenas sobre plugins e temas. Nesta seção, também discutiremos a ajuda online, APIs REST e uma coisa curiosa chamada microconteúdo.

Plug-ins do WordPress

A documentação do plugin WordPress precisa atender a duas multidões: usuários e desenvolvedores. As necessidades de documentação de cada um são diferentes, assim como o estilo de escrita usado.

Usuários

As necessidades de documentação dos usuários giram principalmente em torno de solução de problemas e configuração. Acrescente a isso que você precisa apresentar seu plugin de maneira atraente para que os usuários o experimentem. Cada plugin tem sua própria página no mercado de plugins do WordPress. Tenha em mente os seguintes pontos:

Escreva uma descrição atraente e útil que incentive o download e o uso.
Adicione capturas de tela anotadas da página de configuração do plug-in do painel com descrições.
Coloque perguntas no FAQ que sejam úteis e não banais.
Tenha um Changelog atualizado e bem escrito. Não adicione notas enigmáticas ou concisas lá.

Você deve se lembrar que quando os usuários estão usando a documentação, eles provavelmente estão com pressa e ansiosos para encontrar uma solução. Escreva de forma clara, simples e concisa. Não torne mais difícil para eles do que já é.

Desenvolvedores

Além de seguir as melhores práticas de software e padrões oficiais de codificação PHP, você deve focar sua atenção nas seguintes áreas:

ganchos de plug-in

Estes fazem o trabalho de modificar o comportamento do WordPress. Muito provavelmente o seu plugin WordPress usa isso. Como os ganchos de plug-in são uma parte importante do código, você deve documentar como os usa e em quais funções do WordPress eles estão envolvidos.

tags de modelo

As tags de modelo são outra maneira de um plug-in do WordPress aprimorar a funcionalidade. Documente as funções de tag de modelo que você escreveu. Inclua exemplos de como outros usuários ou desenvolvedores podem usar as tags em seu site WordPress.

opções

As opções são uma maneira de armazenar informações específicas em um banco de dados do WordPress. Isso é feito através das funções add_option e get_options. Nesse caso, documente os parâmetros que você passa para essas funções.

base de dados

Plugins frequentemente lêem e escrevem muitas coisas diferentes de um banco de dados. Como essas são operações fundamentais, documentá-las ajudará muito outros desenvolvedores a entender como seu plug-in funciona.

Temas do WordPress

Existem duas áreas diferentes nas quais você pode criar documentação para temas. O primeiro são os arquivos de origem. Arquivos CSS comentados são mais fáceis de entender e ler do que aqueles sem. Use uma ferramenta como css_doc para ajudá-lo. Isso gera um estilo de documentação JavaDoc e pode ser publicado:

A outra área são os guias de estilo. Esses documentos descrevem a aparência dos elementos e em quais casos eles precisam ser usados. Eles reforçam a consistência e também facilitam a colaboração. Você pode ler o artigo 20 exemplos impressionantes de guias de estilo de marca da Hubspot, pois contém muitos exemplos excelentes.

Novamente, não se esqueça de consultar os padrões oficiais de codificação CSS do WordPress.

Documentar elementos de design com tantos detalhes também ajuda na integração de novos funcionários se você for uma agência WordPress. Os guias de estilo podem ser usados como tutoriais ou material de referência para trabalhos de clientes novos e anteriores.

Ajuda online

Como a ajuda on-line visa resolver um problema específico do usuário, começar com uma lista de tarefas e problemas comuns é o caminho a seguir. Embora a lista a princípio não seja exaustiva, reserve um tempo para produzir o maior número possível de itens concretos. A ideia é escrever um arquivo de ajuda online para cada uma dessas tarefas e problemas e vinculá-los a informações relacionadas. Você pode criar jornadas de usuário para mapear os diferentes caminhos que um usuário pode seguir e fazer em seu aplicativo. Mergulhar em e-mails de suporte para observar perguntas comuns e áreas problemáticas é uma boa maneira de manter sua base de conhecimento atualizada e útil.

Barry J. Rosenberg, autor de Spring into Technical Writing oferece os seguintes conselhos para escrever bons arquivos de ajuda:

Mantenha cada arquivo de ajuda o mais breve possível. Prefira listas numeradas a listas com marcadores. Não divague, não faça notas de rodapé e não queira. Mantenha cada arquivo de ajuda focado em uma única tarefa discreta.

Microconteúdo

Microconteúdo tem duas definições: a primeira é que é conteúdo como títulos e seções que os usuários percorrem, a fim de obter a essência de um determinado artigo. O segundo são pequenos pedaços de conteúdo que podem se sustentar sozinhos e são usados para aprimorar a experiência do usuário. Um excelente exemplo particular que temos em mente é o trecho “várias pessoas estão digitando...” do Slack. (embora o Slack esteja cheio de microconteúdo excelentemente escrito).

Esse bit é acionado quando mais de 3 pessoas estão digitando simultaneamente no mesmo canal. Em vez de apenas imprimir uma lista de pessoas que digitam atualmente, o Slack pega essa informação chata e adiciona um pouco de diversão a ela. A discussão está começando a ficar muito quente, e isso mostra. É um excelente exemplo de como a documentação do produto (as mensagens do aplicativo fazem parte disso, não?) faz com que as pessoas falem sobre você (e criem memes hilários como o acima).

API REST

Documentar APIs REST é uma arte separada por si só. Como em toda redação técnica, você deve buscar concisão, clareza e simplicidade nas definições. Como as APIs REST têm seu próprio formato e complexidade, você não poderia fazer nada pior do que estudar o excelente guia para documentar APIs de Tom Johnson em seu blog I'd Rather Be Writing.

Colaboração e planejamento de documentação

Em última análise, a documentação deve fazer parte do design do produto. Como tal, você deve abordá-lo como tendo um pipeline extra em seu ciclo de software. Isso significa usar repositórios de software para armazenar a versão de documentação mais atual, usar rastreadores de bugs/problemas para monitorar tarefas e problemas, incluir planejamento de projeto de documentação em seu roteiro e, por último, mas não menos importante, colaborar com outras pessoas. Um esboço aproximado de como começar pode ser o seguinte:

Registre tudo o que o usuário gostaria de saber, bem como as áreas para as quais você precisará escrever o texto.
Depois de ter tudo, agrupe-os em categorias e forme títulos de documentos.
Escreva uma especificação para cada documento detalhando coisas como título, descrição, público-alvo, mídia (que forma o documento terá), duração, quanto tempo levará etc.
Adicione as estimativas das especificações da documentação ao planejamento do seu projeto.

Como a documentação do produto abrange todas as áreas, é quase certo que você precisará trabalhar com diferentes pessoas dentro da organização. É uma boa idéia sentar e concordar com algum tipo de processo de como tudo isso vai acontecer. Como em todo projeto, você deve identificar as partes interessadas que fornecerão assistência técnica, bem como aquelas que revisarão e editarão as alterações.

Deve haver diferentes etapas do processo. Devem mapear onde as informações são coletadas, quando o documento é redigido, quando está pronto para revisão literária, para comentários técnicos, publicação e afins. Enfatize a diferença entre comentários literários, técnicos e relacionados ao conteúdo. Por exemplo, não é realmente útil quando você pede a um líder de equipe para comentar em seu documento e, em vez de informações tecnicamente relacionadas, você recebe pedidos de gramática e pontuação.

Fechamento

A documentação do produto é um ativo que compensa a longo prazo. Dá valor ao seu cliente. Pode até ser tão bom, como a documentação da API do Stripe, por exemplo, que as pessoas elogiam nos fóruns. Isso cria engajamento e anuncia sua marca e seu produto de maneira natural e poderosa. Quando combinado com microconteúdo criativo, alcança o que Mike Puterbaugh quer dizer quando diz que a documentação do produto é a “arma secreta do marketing”.