Uma cartilha sobre como escrever uma boa documentação

Este post foi contribuído pelo autor convidado Jeff Matson. Jeff é o chefe de documentação do GravityForms. Ele é o criador do plugin Heartbeat Control WordPress e é um fã dos anos 90.

Muitas vezes, a documentação é a parte mais subestimada do processo de desenvolvimento. Quando olhamos para os rockstars na comunidade WordPress, normalmente olhamos para desenvolvedores, designers e profissionais de marketing. Pouco se sabe sobre os escritores de documentação que derramaram sangue, suor e lágrimas para garantir que tudo corra bem.

Este post é sobre aqueles que dia após dia olham para infinitas linhas de código para decifrar o que o desenvolvedor estava pensando e o verdadeiro significado por trás do código que existe.

Uma boa documentação é mais do que palavras

Bons redatores de documentação fornecem mais do que um manual de instruções, eles fornecem uma experiência. Conheço excelentes documentaristas, principiantes treinados, e a maior diferença entre eles é entender o cérebro de quem lê. Assim como um romance, a documentação tem um fluxo que mantém o leitor interessado e ingerindo mais informações do que ele percebe.

A documentação de qualidade tem como alvo os usuários com maior probabilidade de lê-la. Ele também fornece um ponto de referência para aqueles que são mais propensos a lê-lo. Por exemplo, ao documentar um gancho específico, normalmente é assumido que um desenvolvedor o lerá, mas e aqueles que têm pouca experiência em desenvolvimento?

Um bom escritor de documentação fornecerá um ponto de referência para aqueles que precisam de um empurrão na direção certa, sem a necessidade de entrar em contato com o suporte para explicar isso para eles.

A documentação tem um impacto maior do que você pensa

A maioria simplesmente ignora a documentação, empurrando-a para o abismo sem fim até não aguentar mais. Eu sou culpado da mesma coisa em alguns casos. O que essas pessoas não percebem é que a cada momento que seu plugin ou tema é deixado sem documentação, a experiência do usuário sofre.

Vamos dar uma olhada no seu tíquete de suporte mais comum. Se você documentasse melhor esse problema, esses tickets desapareceriam completamente? Provavelmente não. Você receberia menos tíquetes sobre o problema e aumentaria a produtividade de você ou de seu agente de suporte? Eu garanto. Acho que todos nós poderíamos usar menos tíquetes de suporte.

Como mencionei anteriormente, a documentação tem um impacto dramático na experiência do usuário. Se o usuário conseguir localizar as informações de forma fácil e eficiente, ele economizou seu próprio tempo e o seu. A expectativa de vida média mundial é de 66,57 anos e seus usuários preferem fazer outra coisa com suas vidas do que mexer em documentação mal escrita.

Se um cliente perceber que você dedicou bastante tempo e esforço à sua documentação, ele irá, conscientemente ou não, apreciá-lo melhor. Uma boa documentação mostra que você se importa com eles após a venda inicial.

Você já ficou alto e seco depois de gastar dinheiro suado e logo se arrependeu da compra? Acho que todos nós temos. Com a documentação adequada, você pode evitar passar essa sensação para seus clientes.

Como você pode escrever uma documentação melhor?

O primeiro passo é parar de evitá-lo. Uma vez que você é bom nisso, escrever documentação é uma experiência mais prazerosa do que você pensa. Na verdade, isso se tornará uma segunda natureza. Assim como tudo no mundo, a prática leva à perfeição.

Um dos primeiros passos que você deseja tomar ao decidir levar sua documentação para o próximo nível é determinar seus pontos problemáticos. Sobre o que você está sendo contatado? Se você começar a escrever cegamente sobre as coisas, pode descobrir que o que está escrevendo não está causando o impacto que você gostaria.

Uma das melhores técnicas que descobri é rastrear o número de tickets que estão documentados versus aqueles que não estão, e dividir aqueles que não estão em categorias. Dessa forma, você pode direcionar melhor seus pontos problemáticos e revisar as partes que podem não ser tão úteis quanto deveriam.

Depois de determinar qual documentação você deve escrever, você deve determinar seu público-alvo e dividi-lo em desenvolvedores, usuários e usuários avançados. Isso ajuda você a atender a esse público específico. Veremos como segmentar esses usuários um pouco mais tarde.

Em seguida, você deseja dividir o documento. Para desenvolvedores, você vai querer dividi-lo em informações brutas (argumentos aceitos, valores de retorno, etc.), exemplos específicos e casos de uso. Para os usuários, o melhor curso de ação é um passo a passo. Cada passo que eles precisarão dar, independentemente de quão trivial possa parecer, é crítico.

Soletre para eles a cada passo do caminho. Documentar para usuários avançados é muito semelhante a um cenário de usuário, mas mais estruturado e escaneável. Seja claro, mas permita que eles saltem facilmente para onde precisam ir sem ler o passo anterior primeiro.

A arte de escrever melhor documentação

Quando se trata da arte de escrever sua documentação, escreva de uma maneira que melhor atinja seu público, mas também use uma linguagem simples que você saiba que eles entenderão. Uma das melhores razões para isso é devido às traduções. Embora o Google tradutor faça um excelente trabalho, é muito mais fácil traduzir o vocabulário simples de um aluno da 5ª série do que o contido em uma tese de pós-graduação.

Dentro do seu conteúdo, não tenha medo de criar links para conteúdo relevante. Isso permitirá que você evite se repetir em vários documentos, além de permitir que o leitor volte atrás se precisar de mais informações sobre um determinado assunto. Afinal, seus principais objetivos são deixar o usuário feliz e economizar tempo.

O processo de documentação não para depois que você pressiona o botão publicar . Volte e revise todos os documentos conforme necessário. Quase imediatamente após a publicação do documento, volte e veja se os tíquetes de suporte que você rastreou diminuíram e o tráfego para esse artigo específico aumentou. Normalmente, se você está recebendo mais tráfego para um artigo, está ajudando. Se você está recebendo mais tráfego, mas o mesmo número de tíquetes de suporte, convém consultar esse artigo para ver o porquê.

O que aprendemos

Primeiro, espero que, depois de chegar até aqui, você tenha uma melhor apreciação por aqueles que estão nas trincheiras escrevendo a documentação que a maioria de nós dá como certa. É realmente uma forma de arte que muitos de nós que escrevem documentação para viver realmente apreciam e dedicam muitas e muitas horas.

Também espero que você saia deste artigo pensando mais sobre sua documentação existente e como ela pode ser melhorada. A documentação adequada pode ser extremamente gratificante e, uma vez praticada, pode ser bastante divertida de escrever.

Documente com antecedência, documente com frequência. Um ótimo produto é mais do que um ótimo código, também é muito bem documentado.