Considerado um dos cientistas mais influentes da área da computação, o canadense David Parnas uma vez disse que “a principal causa do lamentável ‘estado da arte’ no desenvolvimento de software é nossa falha em produzir uma boa documentação de software”.
O argumento de Parnas tem fundamento, afinal uma documentação incompleta ou desatualizada gera diversos impactos, desde o maior risco a erros no desenvolvimento até a menor eficiência em outras etapas do processo de desenvolvimento de software.
Mas por que isso acontece? Neste artigo, vou te mostrar:
- Os critérios que fazem uma documentação ser considerada boa.
- Os tipos de documentação que existem em projetos de software.
- Quais tipos de documentação você deve, ou pode, usar em seu projeto.
Para começar, o que seria uma documentação de software?
Quando falamos sobre documentação de software (ou de código), estamos nos referindo a qualquer material textual que times de engenharia, teste, produto e demais profissionais utilizam para realizar o seu trabalho.
Mas não somente isso: a documentação deve ser uma descrição precisa sobre um sistema de software. Quanto maior a precisão desses documentos, maior o status de autoridade que eles podem ter.
Aliás, documentações de software podem ser utilizadas como fonte de evidência. Se está escrito, então é lei.
Documentações devem abstrair a tecnicidade de um assunto – seja de implementações, configurações, etc. – e focar no que é essencial para o usuário, trazendo informações completas e imprescindíveis para que você possa alcançar um objetivo e/ou realizar uma ação.
Uma boa documentação é aquela capaz de apoiar o time nas etapas de desenvolvimento, compreensão e manutenção de código. Deve ser, também, capaz de auxiliar usuários e quem mais tiver interesse em conhecer mais sobre o sistema de software e seus processos relacionados.
Para que isso aconteça, é necessário que você identifique qual tipo de documentação a sua equipe/projeto deve investir esforço e qual é o perfil das pessoas que lerão os documentos criados.
Vou falar disso mais adiante, mas antes precisamos entender o porquê da documentação está aquém do ideal na maioria dos projetos.
As “dores” provocadas por não se fazer documentações
Em um levantamento publicado em 2019 (em inglês) com mais de 800 documentos de software, desde pull requests no GitHub a threads no StackOverflow, o time de pesquisa criou uma taxonomia que elenca os principais problemas reportados em documentação de software.
A seguir descrevemos brevemente cada um destes problemas.
- Incompletude (268 ocorrências): quando a documentação não tem todas as informações (seja de um sistema ou de seus módulos) necessárias para que profissionais/usuários realizem suas tarefas.
- Falta de atualização (190 ocorrências): quando um documento está desatualizado em relação ao que um sistema é/faz. Na prática, é a capacidade da documentação acompanhar as mudanças que um projeto sofre no meio do processo.
- Pouca usabilidade (138 ocorrências): refere-se ao grau em que a documentação pode ser usada por quem lê para alcançar seus objetivos de forma eficaz, incluindo a experiência dos usuários (UX) com a documentação.
- Pouca legibilidade (107 ocorrências): quando a documentação é fácil de ler. Isso é possível quando as informações do documento são ordenadas de forma que o conteúdo fique acessível ao seu público.
Diante dessas “dores”, você deve estar se perguntando: quais desses problemas doem mais no seu time ou projeto? É possível priorizá-las?
Critérios de uma boa documentação de código na visão de quem atua na Engenharia de Software
O mesmo time de pesquisa, ciente das dúvidas que as pessoas costumam ter de “por onde começar”, publicou um novo trabalho (em inglês) em busca das respostas de como criar uma boa documentação de código.
Nele, o grupo pediu que profissionais de Engenharia de Software priorizassem, em sua visão, quais eram as principais dores de documentação com base na taxonomia criada no estudo anterior (Completude, Atualidade, Usabilidade e Legibilidade).
Entre os resultados da pesquisa, alguns fatos:
- Para devs, os maiores problemas estão em documentações que ferem os critérios de completude, atualidade e legibilidade.
- Esses problemas, aliás, foram listados como rotineiros pelas pessoas que responderam à pesquisa.
- Apesar de não ter chamado atenção no primeiro estudo, neste o problema de “corretude” (leia-se: documentações com informações erradas) apareceu como uma dor no dia a dia de trabalho.
Você identificou algumas dessas dores no seu projeto?
Sem dúvida, criar, manter e evoluir documentos técnicos que sejam corretos, completos, atualizados, além de serem fáceis de usar e ler, não é uma tarefa nada fácil.
É mais prudente que times sejam capazes de refletir quais dessas características fazem mais sentido para cada equipe e projeto e, assim, destinar esforços localizados para trabalhar nas características que fazem mais sentido.
Quais são os tipos de documentação de código que posso usar no meu projeto?
Existem diversos tipos de documentação, sendo cada tipo útil para situações diferentes.
O livro Software Engineering at Google conta com um capítulo sobre documentação de software. Os autores (Titus Winters, Tom Manshreck e Hyrum Wright) listam diversos tipos de documentações técnicas, por exemplo:
- Documentação de referência.
- Documentos de design.
- Tutoriais.
- Documentação conceitual.
- Landing pages.
Cada tipo de documentação tem seu propósito específico que deve ser seguido à risca.
Assim como uma API, que deve fazer uma única coisa (e bem), o ideal é que você evite criar documentos universais, mas sim documentos de propósitos diferentes, organizados em uma ordem lógica.
Claro que essa lista está longe de ser definitiva. Um exemplo é o estudo que levantou as “dores de documentação” que citamos anteriormente. Nele, também encontramos os tipos de documentos considerados úteis por devs.
Neste trabalho, os tipos de documentação foram levantados com base na taxonomia de problemas identificados, o que resultou numa lista com 13 itens:
- API reference.
- Comentário de código.
- Guia de contribuição.
- Guia de deploy.
- Guia de migração.
- Guia de instalação.
- Guia de primeiros passos.
- FAQ.
- How-to/Tutorial.
- Release Note/Change log.
- Manual de usuário.
- Tutorial em vídeo.
- Threads no StackOverflow.
Considerando que utilizaram plataformas como GitHub, StackOverflow e lista de e-mails como base para a pesquisa, é esperado que os tipos de documento encontrados sejam os mais comuns nestas plataformas. Por exemplo, o guia de contribuição, comumente encontrado nos projetos do GitHub.
Isto, por outro lado, explica o porquê de documentos comuns em ambientes empresariais (como documentação da arquitetura do software ou documentos de visão sobre o produto) não foram citados.
Em seguida, o time de pesquisa fez um outro questionário para priorizar esses itens.
Nessa lista, foi observado que documentos como comentários em código e contributing guideline foram os considerados mais úteis em diferentes atividades do desenvolvimento de software. Curiosamente, quem respondeu a pesquisa viu menor importância em tipos de documentos como guias de migração.
Conclusões sobre os estudos analisados
Em resumo, essas pesquisas mostraram que diferentes tipos de documentação tem diferentes graus de importância e qualidade. Dessa forma, cabe ao time de desenvolvimento decidir qual tipo de documentação faz mais sentido ser adotado.
Essa decisão deve ser tomada de acordo com o contexto do projeto, as habilidades do time e o perfil de quem vai consumir esse conteúdo.
Para auxiliar nesse processo, a Zup conta com uma equipe de Technical Writers que atua junto de equipes de desenvolvimento, apoiando-os não somente na construção de melhores documentações técnicas, mas também na definição de estratégias de planos e fluxos de documentação.
Escreva documentação com foco na sua audiência
Ao criar uma documentação de software, é natural que a gente acabe projetando nossa realidade e assumindo que ela é igual a de quem lê.
Nesse caso, quem escreve acaba assumindo uma série de suposições, por exemplo:
- “Todo mundo sabe o que esse comando faz, não preciso explicar”;
- “Como eu já tenho a linguagem e a IDE instalados, eu posso escrever somente a parte de configuração”;
- “Como eu só uso Linux, não vou escrever o passo a passo pro Windows”.
No entanto, a gente esquece que nem sempre quem lê a documentação terá as mesmas habilidades técnicas, muito menos deverá ter um ambiente de trabalho similar àquele de quem desenvolveu o código.
Por isso, quando devs escrevem para si, essas diferenças acabam passando despercebidas, e só são notadas quando um usuário leitor as reporta (quando faz esse reporte).
Aliás, é por esse motivo que contar com apoio de Technical Writers nos times de desenvolvimento contribuem para que as documentações sejam escritas respeitando os diferentes contextos que quem lê tem e, assim, garantindo que os documentos atendam às necessidades dos usuários.
Escute o episódio do ZupCast “UX Writing e Technical Writing: conheça as diferentes escritas para produtos digitais” e conheça mais sobre essas duas atuações:
Conhecer a sua audiência implica não somente em saber quem são os usuários leitores, mas também em identificar que tipo de documentação eles deverão consumir.
Por exemplo, um tutorial deve fornecer instruções explícitas para usuários com pouca ou nenhuma familiaridade com a base de código, enquanto que um guia de referência de uma API precisa fornecer informações de uso da API para usuários experientes e inexperientes.
“Eu não escrevo documentação pois o meu programa é um documento vivo”
Talvez você já tenha escutado (ou até comentado) a frase acima em algum momento na sua carreira profissional. Essa crença é tão conhecida que até mesmo o Brad Smith (então Senior VP da Microsoft), comentou que “o código fonte do Windows é a documentação final das tecnologias Windows Server”.
Não é difícil pensar em fatos que ajudam a apoiar essa crença. Por exemplo: nós usamos um conjunto parecido de habilidades para ler um texto e para ler um código na tela do nosso computador.
Muitas vezes, inclusive, usamos os mesmos programas para as duas atividades. Quem nunca teve duas abas do VS Code, em que uma era um arquivo Markdown e a outra era uma classe Java?
No entanto, essa crença captura apenas uma pequena parte da história. Nos dias de hoje, os sistemas de software são extremamente complexos. Imagina você pedir para que a pessoa programadora recém-contratada se familiarize com toda a base de código no primeiro dia do trabalho. Não parece razoável, não é? Além do que, isso poderia facilmente atrasar o processo de onboarding dessa pessoa no time.
Para se ter uma ideia, um estudo da Panopto mostrou que as pessoas gastam, em média, 5 horas por semana esperando por informações para fazer seu trabalho; 60% delas, inclusive, admitem ser quase impossível obter informações de colegas.
Em outras palavras, os times de desenvolvimento precisam de documentações que extraiam somente as informações essenciais, abstraindo os detalhes técnicos que residem no código fonte. Quando for necessário, alguém mais experiente poderá consultar o código fonte (de maneira mais direcionada) para solucionar dúvidas técnicas.
O ideal é que essa consulta aconteça somente quando necessário, e não a todo momento.
Documentação como cidadã de primeiro nível
Embora o código fonte não deva ser visto como uma forma de documentação, a tarefa de escrever documentação deve ser similar à tarefa de escrever código fonte. Assim como escrevemos código respeitando regras de sintaxe e estilos de codificação, devemos adotar regras similares para nossa documentação.
No capítulo sobre documentação no livro “Software Engineering at Google”, os autores sugerem que documentos técnicos devem sempre respeitar a gramática da língua em que o documento está escrito para padronizar o texto e, assim, evitar confusão e/ou distração para quem lê.
Por isso, é importante que os times de desenvolvimento adotem também um padrão de escrita de seus documentos técnicos. Os autores também apresentam uma segunda similaridade entre documentos técnicos e código fonte: os dois precisam de donos. Documentos que não tem donos se tornam desatualizados com mais frequência e, assim, se tornam difíceis de manter.
Na Zup, a equipe de Technical Writers também tem como responsabilidade garantir que todos os documentos técnicos tenham seus próprios donos.
Pensar em ownership de documentos também facilita o ingresso dos documentos como cidadãos de primeiro nível no processo de desenvolvimento de software. Dessa forma, documentos podem (e devem) participar do processo de revisão de código, serem linkados em sistemas de gerenciamento de bugs, etc. Afinal, assim como código, documentações podem estar duplicadas ou depreciadas.
Docs as Code
Tornar a documentação de código como cidadã de primeiro nível implica em (o tanto quanto possível) tratá-la como código. Tratar documentação como código, ou seja como Docs as Code, implica em:
- Residir em um sistema de controle de versão para os documentos.
- Saber quem são os donos da documentação.
- Passar por revisões por pares a cada mudança.
- Reportar suas inconsistências e deficiências em um sistema de gerenciamento de bugs, etc.
Como usamos essas abordagens de documentação de software na Zup e onde desejamos melhorar
No livro Software Engineering at Google os autores comentam que, para mudar esse status quo, as organizações precisam adotar práticas, processos e ferramentas que deem destaque e apoio ao processo de criação de documentação de software.
Os autores destacam que no Google, em particular, “nossos esforços mais bem-sucedidos têm sido quando a documentação é tratada como código e incorporada ao fluxo de trabalho tradicional da engenharia”.
Na Zup EDU, estamos trabalhando em um projeto de desenvolvimento em que a documentação de software está sendo tratada como cidadã de primeiro nível. Ainda estamos no começo do projeto, mas, idealmente, gostaríamos de chegar no ponto de bloquear releases de novas funcionalidades se a documentação destas estiver deficiente.
Ao promover a documentação de código, esperamos que o conhecimento que antes era tácito torne-se explícito, ajudando assim atividades de recuperação de informação, que são basilares para o processo de manutenção e evolução de código.
A Zup também conta, em algumas equipes, com profissionais de Technical Writing que contribuem para que a abordagem de documentação como código seja respeitada, garantindo documentos técnicos que atendam ao seu público. É o caso dos nossos produtos Open Source.
Inclusive, quer conhecer mais sobre como a documentação pode ser uma excelente porta de entrada para o mundo Open Source? Então assista a essa live:
Documentação de Software: a chave para soluções melhores
Muito do que quis trazer aqui não é novidade. De fato, alguns dos problemas sobre documentação de software que existem hoje, em 2022, são similares aos que David Parnas escreveu na década de 80 e 90.
Em resumo, escrever boas documentações vai além do texto: é sobre identificar quais são as informações que precisam ser registradas e padronizadas para ajudar alguém que, como você, quer se familiarizar sobre um assunto que ainda não tem tanto domínio.
Na sua equipe/projeto, como vocês tratam a documentação do software? Conta pra gente nos comentários 🙂
