Como escrever boas documentações
Este artigo nasceu de uma confissão no Twitter (obrigada, Carol Soares, pela sugestão!):
Pois é: eu amo produzir documentações. E também amo ler documentações.
Mas eu sou estranha. Por exemplo, eu sou a única pessoa que conheço que sempre lê o manual de instruções. No mês passado, montei um apartamento e a minha leitura de cabeceira se tornou uma pilha de manuais de eletrodomésticos e eletroportáteis. Ontem, terminei o manual da geladeira e achei o final meio frio (…desculpa).
A verdade é que, leitor da Brastemp ou não, ninguém escapa de precisar ver instruções na vida e a experiência fica muito mais difícil se esse documento estiver incompleto ou confuso.
No contexto de tecnologia, documentações têm múltiplas funções:
- Formalizar processos e sistemas
- Aprender em voz alta
- Ajudar pessoas a responder suas próprias perguntas
Em todos os casos, tanto quem escreve quanto quem consome são beneficiados pela produção do material. Se você quer participar dessa troca de conhecimento, segue abaixo um guia completo sobre como escrever boas documentações!
Antes de começar
Apesar do paralelo traçado anteriormente, elaborar uma documentação de software é bem mais complexo que um manual de aparelho. Isso porque não existe um conjunto de instruções fechado que pode ser impresso e nunca mais revisado. Tecnologia muda constantemente, e os sistemas mais usados são os que mais se atualizam. Portanto, as documentações mais importantes são as que ficam desatualizadas mais rápido!
Nada animador, mas remediável: na maioria das vezes, não é a doc inteira que fica obsoleta de uma vez. São os detalhes operacionais, mais técnicos. Então, um caminho é separar o como do porquê. Como usar o sistema muda constantemente, mas por que o sistema existe é um conceito mais estável.
Essa foi a idéia da Etsy, que fez um experimento mirando em documentações "imutáveis". Seguir esse conceito à risca acaba envolvendo outras ferramentas e tornando o processo mais complexo, mas podemos tirar uma lição simples e bem aplicável (TL;DR): sempre que possível, evite detalhes muito específicos que podem mudar. Por exemplo: em vez de dizer "Usamos a fonte Roboto", você pode orientar a pessoa a buscar a fonte do projeto na tag <head> do arquivo index.html.
Primeiros passos
Uma nova página em branco pode intimidar ao ponto de paralisar até a mais experiente das pessoas escritoras. Aqui, temos a vantagem de poder começar com um plano definido, sem precisar pensar muito. Costumo sempre seguir três passos, nessa ordem:
- Recolher materiais de referência
- Listar o conteúdo em tópicos macro
- Acrescentar pormenores e parte técnica
Antes de começar a escrever o Readme do Astro (design system da Magnetis), primeiro deixei abertas todas as referências que usaria. Depois, listei as informações que já sabia que o documento precisaria conter. Nesse momento, não me preocupei muito com a ordem delas:
Astro Readme
- Instruções para importar a dependência no seu projeto
- Como acrescentar as fontes
- Como rodar o projeto localmente
- Onde visualizar a documentação online
- Como editar a documentação
- Como fazer deploy da documentação
- Suporte oficial para React
- Erros conhecidos para troubleshooting
Agora que a página não está mais em branco, ficou bem mais fácil de prosseguir detalhando cada um desses passos. Antes disso, porém, vamos entrar em detalhes sobre a estrutura desse documento.
Título e introdução
A pergunta que você deve responder ao elaborar o título e o primeiro parágrafo da sua doc é: "Pra que serve esse documento?"
Procure escrever um título que já deixe claro do que se trata aquele texto. E caso a pessoa tenha alguma dúvida, o primeiro parágrafo serve de apoio para entender se é nesse documento que ela vai encontrar a informação que procura.
Guia de Acessibilidade Mobile
Este documento é um guia de referência para descobertas recentes e novas práticas que devem ser disseminadas em nosso projeto para continuamente melhorar a acessibilidade do mobile app. Neste momento, nossos esforços estão focados nos leitores de tela VoiceOver (iOS) e TalkBack (Android).
Itens ou passos do processo
Agora, já podemos retomar aquela lista de informações que mapeamos lá no primeiro passo. É um bom momento para tentar organizar esses passos ou itens na mesma ordem em que a pessoa precisará consultá-los. Por exemplo, Instalação e, depois, Como usar.
A melhor forma de apresentar o conteúdo pode variar dependendo do tipo de processo a ser descrito. Instruções passo a passo ficam mais claras se enumeradas; opções de ação sem ordem definida ficam bem organizadas em tópicos; um assunto menos técnico pode ficar bem resolvido com um FAQ, e assim por diante. Na dúvida, teste mais de um formato antes de definir.
Use títulos bem descritivos em cada um deles, para possibilitar a localização rápida da informação necessária. Isso também lhe ajudará a criar um bom índice, mais tarde.
Troubleshooting
Em docs mais técnicas, uma seção de Troubleshooting (solução de problemas) pode ser especialmente útil para documentar erros e obstáculos conhecidos e mostrar o caminho para contorná-los. É importante manter essa seção atualizada, visto que não é incomum passarmos mais tempo tentando solucionar bugs do que desenvolvendo de fato.
Contato
Na maioria dos casos, é interessante que ao final do documento conste um canal de contato para sanar dúvidas e enviar sugestões. Se for um Readme no GitHub, essa seção também pode orientar sobre como e quando abrir uma issue no repositório.
Referências
Incluir links dos materiais usados como referência no final da doc é uma boa prática tanto para creditar os autores quanto para leitores que possam se interessar em conhecer melhor aqueles assuntos.
Tenha em mente
Enquanto cria essa documentação, sugiro que tenha em mente algumas questões que ajudam a cobrir o máximo de território possível:
- Quem lerá essa documentação — e qual o nível técnico?
Essa doc será consumida por pessoas dentro de um time numa empresa, ou pelo público em geral num projeto open source? É preciso adaptar o nível técnico ou detalhamento de acordo com o contexto de quem lerá, mantendo o texto tão didático quanto possível. Lembre-se de que o óbvio é relativo; às vezes, achamos que qualquer um entende aquilo que consideramos simples, mas isso nem sempre é verdade (alô, síndrome do impostor!).
- Antecipar perguntas
É basicamente um exercício de empatia: tente antecipar as dúvidas que possam surgir ao longo do texto e já respondê-las no mesmo local de aparecimento.
- Single source of truth
O conceito de "single source of truth" (única fonte da verdade) prega que um único local seja mantido como fonte de consulta para todas as questões relativas a um assunto. É mais fácil manter as atualizações sob controle em um único local, portanto essa é uma boa prática a se buscar.
- Saber a hora de parar
Um documento desnecessariamente longo é um documento difícil de ler e de manter. Tente delimitar até onde explicar um tópico dentro da doc ou quando é hora de linkar pra um tutorial externo mais especializado. Para pessoas mais avançadas que possam precisar de mais detalhes, essa é uma forma de dar o caminho sem penalizar as outras com conteúdo extra.
- Ficar dentro do escopo
Ainda na linha do item anterior, é preciso ser tão objetivo quanto possível. Se um processo tangente começar a ficar muito detalhado, pode ser necessário separá-lo em outra documentação.
- Linkar, não replicar
Reforçando esse ponto colocado anteriormente, evitar detalhes que podem facilmente mudar diminui drasticamente a frequência com que a documentação ficará desatualizada. Se os detalhes inconstantes em questão puderem ser encontrados em uma fonte externa mais atualizada (por exemplo, informações sobre um plugin ou dependência de terceiros), é melhor linkar a ela do que replicar esse conteúdo dentro da sua documentação.
Detalhes que enriquecem
Já cobriu todos os pontos anteriores e quer levar um passo além? Eis alguns detalhes que enriquecem a experiência de quem consumir a sua doc.
- 1 referência = 1 link
Sempre que fizer uma referência a um conceito ou processo, como por exemplo Markdown, selecione um material complementar sobre aquele assunto e crie um link. Assim, uma pessoa que não saiba exatamente do que se trata ou queira detalhes pode consultar uma fonte selecionada por você, o que garante que vocês estarão na mesma página (pun intended).
- Ilustrar com imagens
Screenshots, gifs, ilustrações, gráficos, memes… Escolha a melhor forma de ilustrar o conteúdo e use quantas figuras forem necessárias pra tornar o texto mais dinâmico e didático.
- Hierarquia de informação
Quem tem contato com design já tem familiaridade com esse conceito: a idéia é estabelecer uma hierarquia visual para facilitar o entendimento rápido e localização das informações. A aplicação mais útil aqui é explorar a formatação do texto para criar níveis de título e subtítulo (como os headings de h1 a h6 no HTML), e assim agrupar conjuntos macro e micro de informações. Podemos também usar negrito, itálico e até mesmo cores (como o vermelho em pontos de atenção) para adicionar entonação ao texto, da mesma forma que faríamos no discurso falado.
- Exemplos práticos
Quando for possível, crie um exemplo de uso do processo descrito para ilustrar sua aplicação na prática. Esse detalhe sempre fará toda a diferença na clareza da mensagem.
Acabei, e agora?
Segura essa vontade de clicar em "Publicar"! Agora é hora de tirar as rebarbas e dar aquele acabamento caprichado pra sua doc ficar redondinha. Só mais alguns passos:
- Reler do começo ao fim
Na hora de escrever, é normal ir e voltar várias vezes e trocar parágrafos de lugar. Ler do começo ao fim ajuda a revisar a coesão do fluxo do texto sem interrupções.
Hora de mandar uma dica super importante sobre escrita em geral: a esmagadora maioria das pessoas não lê, escaneia. Por isso, é preciso testar a eficácia daquela hierarquia de informação, verificando se é possível pular direto pra um tópico no meio do texto e entender o que está acontecendo ali. É isso que a maioria das pessoas fará na sua doc, por melhor escrita que ela esteja (sinceridade!).
- Editar
Nessa revisão, além de encontrar pontos que podem ser melhorados, é sempre bom procurar enxugar, resumir e cortar partes redundantes ou desnecessárias. Lembre-se: as pessoas já não lêem tudo, então quanto menos excesso, mais clareza na mensagem.
- Criar o índice
O índice, ou "Table of contents" como muitos chamam, serve para facilitar a pré-visualização do conteúdo e também para navegação rápida no texto. Se a ferramenta permitir âncoras (links que levam a pontos da mesma página), abuse delas.
- Pedir revisões
Peça a revisão de pessoas familiarizadas com o sistema documentado, pra que elas validem se você cobriu todos os pontos e se não esqueceu de nada. Depois, peça a revisão de pessoas não familiarizadas. Essa é a parte mais importante para simular como uma pessoa nova entenderá a documentação, e geralmente é onde se recebe mais feedbacks.
- Atualizar sempre
Depois de publicar a doc, é fácil se esquecer dela para sempre. Uma documentação de tecnologia nunca está terminada; a melhor prática é eleger uma pessoa ou grupo responsável por mantê-la.
Lembrete final
É importante ter documentações bem escritas e atualizadas, mas o software em si é ainda mais importante. Não queremos nos perder em detalhes e esquecer qual é a nossa prioridade, como lembra o manifesto Agile:
Working software over comprehensive documentation.
(tradução: software funcionando acima de documentação abrangente)
Essa prioridade é especialmente válida no contexto de uma empresa fechada. Mas, naturalmente, em um projeto público ou open source, a máxima tem suas ressalvas. Afinal, sem documentação, é impossível compreender código de terceiros e, principalmente, contribuir.
O lembrete final é sempre adaptar o nível de dedicação com a documentação ao seu contexto.
Por hoje é só e até a próxima ❤
