Clarice Abreu dá dicas de quais os tipos de documentação mais utilizados, boas práticas na hora de adotar esse documentos e como estimular eles sejam bem escritos e bem utilizados; saiba mais
É comum existirem controvérsias quando o tema é documentação de software. Há quem ame e há quem odeie. Fato é que a documentação, quando bem escrita e bem utilizada, aumenta a probabilidade da construção e manutenção de softwares bem-sucedidos, ou seja, softwares que atendam às expectativas tanto das pessoas usuárias quanto das engenheiras [1].
Por outro lado, é inegável que manter uma documentação de qualidade apresenta custos e demanda esforços. Então, como podemos nos certificar de que estamos produzindo documentação que aumenta a eficiência do desenvolvimento de software ao invés de diminuí-la?
O primeiro passo é entender o que é documentação e quando ela pode ser produzida. Podemos definir documento de software como qualquer artefato cuja finalidade é comunicar informações sobre o sistema ao qual se relaciona [2].
Essa definição pode parecer vaga, mas o objetivo é exatamente esse. Essa documentação pode ser produzida de inúmeras formas, e até comentários de código e descrição de commits são considerados formas de documentar. Além disso, ela pode ser escrita e utilizada durante todo o ciclo de desenvolvimento, desde o planejamento até a conclusão e manutenção.
Quais tipos de documentação existem?
Dentre os vários tipos de documentação, alguns dos principais são:
Documentação de processo
Registra informações sobre as etapas necessárias para o desenvolvimento de um projeto de software. Ou seja, pode conter informações sobre o planejamento do projeto, seus requisitos, suas estimativas, seu cronograma, quais decisões foram tomadas no decorrer de sua execução etc.
– Quando deve ser produzida? Assim que um projeto começa a ser planejado esse tipo de documentação já pode começar a ser escrita. Além disso, deve ser atualizada sempre que houver uma mudança de planos ou de requisitos.
– Quais são os seus benefícios? Mantém a equipe de desenvolvimento informada, orienta os membros do time em relação ao seu papel no processo e ajuda as pessoas envolvidas a atingir os objetivos do projeto com eficiência.
Documentação de arquitetura
Descreve os principais componentes de uma aplicação ou serviço, como eles funcionam e como se relacionam. Esse tipo de documento mapeia a estrutura do software possibilitando uma visão geral do sistema, além de expor as convenções utilizadas naquela aplicação. Diagramas costumam ser muito bem vindos nesse tipo de documentação.
– Quando deve ser produzida? Uma documentação de arquitetura pode ser desenvolvida para apresentar uma proposta de como um sistema pode ser construído ou refatorado. Nesses casos, ela é escrita antes do início do desenvolvimento. Esse tipo de instrumento também pode ser utilizado para expor o funcionamento atual de um sistema — aqui, ele deve ser desenvolvido após a conclusão da construção dos componentes retratados.
– Quais são os seus benefícios? Facilita o entendimento do funcionamento e da estrutura de um sistema, a discussão de trade-offs de diferentes arquiteturas, a manutenção e a refatoração.
Documentação de serviço
Reúne informações importantes sobre determinado serviço como gráficos para monitoramento, instruções para manutenção, links úteis, indicação das pessoas responsáveis pelo serviço etc.
– Quando deve ser produzida? Conforme o serviço é desenvolvido e utilizado, esse tipo de documentação deve ser enriquecido.
– Quais são os seus benefícios? Possibilita que uma pessoa que tenha pouco ou nenhum contexto sobre um serviço consiga obter informações úteis sobre ele e, possivelmente, entenda como resolver problemas comuns relacionados a ele ou encontrar pessoas com quem possa tirar dúvidas.
Guidelines
Expõe um passo a passo de como realizar determinada ação — por exemplo, como adicionar ou remover componentes de um serviço, como executar uma aplicação e outras atividades que sejam executadas com certa frequência por diferentes pessoas.
– Quando deve ser produzida? Quando for identificado que uma ação será realizada repetidamente e os passos para fazer isso não são intuitivos.
– Quais são os seus benefícios? Aumenta substancialmente a autonomia e independência de novas pessoas integrantes do time de desenvolvimento, uma vez que diminui a necessidade delas de perguntar para outras integrantes como realizar tarefas frequentes.
Como avaliar a qualidade de um documento?
Além da produção de documentação, outra atividade essencial é a avaliação da qualidade dos artefatos produzidos. Alguns dos critérios que podem ser utilizados para isso são os seguintes:
– Acurácia: o documento deve apresentar informações precisas que sejam representações fiéis do estado atual do conteúdo ao qual ele se relaciona, ou seja, deve ser consistente, correto, completo e atualizado.
– Utilidade: o documento deve ser útil e trazer benefícios à pessoa que o lê. Os objetivos do artefato produzido devem ser totalmente atendidos após a sua leitura.
– Legibilidade: o documento deve ser facilmente entendível para seu público alvo. Deve-se evitar palavras pouco conhecidas e, no caso de elas serem necessárias, seus significados devem ser explicados.
– Acessibilidade: o documento deve ser acessível para seu público e fácil de ser encontrado. A sua leitura deve ser indicada sempre que pertinente.
– Responsabilidade: o documento deve ter pelo menos uma pessoa responsável por manter sua qualidade. Além disso, também é relevante mostrar essa informação ao leitor para que ele possa tirar dúvidas ou fornecer feedback.
Como a documentação pode aumentar a eficiência do desenvolvimento de software?
Documentos que trazem os maiores benefícios são aqueles que têm sua qualidade avaliada e melhorada regularmente. Quanto mais disseminada a cultura de revisão e correção de documentos, maior será a confiança das pessoas neles.
A confiança é um elemento essencial para possibilitar que a documentação contribua para a eficiência do desenvolvimento de software. Um dos maiores ganhos que ela traz é a diminuição do esforço e do tempo para a aquisição e transmissão de conhecimento — e isso só pode acontecer se as pessoas confiam nesse instrumento.
Quando a documentação é confiável, ela pode ser utilizada para substituir o papel de uma pessoa na disseminação do conhecimento. Além disso, ela evita que erros já cometidos voltem a acontecer. Por exemplo, se uma pessoa do time precisa realizar determinada tarefa e encontra um documento que a ajuda a realizá-la com mais facilidade e agilidade, ela está:
(1) poupando seu tempo e esforço ao evitar tentativas de soluções que não funcionariam;
(2) poupando tempo e esforço de outras pessoas da equipe ao diminuir ou até eliminar a necessidade de que elas parem o que estão fazendo para a ajudar.
Outros benefícios são a descentralização do conhecimento em pessoas específicas que, se saírem do time, não o deixarão órfão de conhecimento; o aumento da padronização e do uso de boas práticas; e a facilitação da tomada de decisão baseada no conhecimento presente.
Por onde começar?
Se o seu time, empresa ou organização não tem uma cultura de documentação estabelecida, uma boa estratégia para identificar por onde começar é analisar em qual parte do ciclo de desenvolvimento há maiores gargalos. Isso facilitará a determinação de quais documentos podem ajudar a mitigar ou remover esses obstáculos.
Por exemplo, se o seu time está tendo problemas com o planejamento e o monitoramento de atividades, o ideal é começar a produzir mais documentações de processo. Por outro lado, se as dificuldades estão mais relacionadas à demora para realizar cada tarefa, é interessante investir em guidelines que indiquem a maneira mais eficiente de realizá-las.
Boas práticas
Alguns dos exercícios que podem ajudar na produção de bons documentos são os seguintes:
- Identifique a finalidade do documento a ser produzido e anote-a separadamente. Para isso, pergunte-se por que esse documento deve ser produzido e o que a pessoa que o tem em mãos deve obter após a sua leitura.
- Identifique o público-alvo do documento. Entenda qual o contexto dessas pessoas, o que você pode assumir que elas já sabem e o que precisará explicar.
- Escreva uma primeira versão do documento reunindo todos os pontos que lhe pareçam importantes.
- Releia a primeira versão e identifique quais partes estão confusas ou repetitivas. A partir disso, refine o documento para que ele seja ao mesmo tempo completo e direto, ou seja, certifique-se de que a pessoa leitora obtenha toda a informação que precise e que não haja algo desnecessário.
- Após a finalização e o refinamento, recupere a finalidade anotada por você no passo 1 e reflita se o seu documento a atende de forma integral. Se não, adicione o que falta.
- Acrescente referências que possam ser úteis, como links para documentações relacionadas e para fonte dos dados ou imagens e, se contundente, recomendações de outras leituras para aprofundar o conhecimento.
- Peça para que outras pessoas revisem seu documento e lhe deem feedback sobre sua qualidade.
- Compartilhe o documento com seu público e adicione links para ele nos lugares em que possa ser útil.
- Crie lembretes para revisar a documentação de tempos em tempos e indique as pessoas responsáveis por ela.
Após disponibilizar o documento ao público, caso em algum momento alguém lhe pergunte algo que esteja explicado nele, ao invés de responder, direcione a pessoa para a sua leitura. Assim você pode obter feedback se a dúvida foi respondida na documentação e se ela está suficientemente completa e clara.
Referências
[1] Nasution, M. F. F. and H. R. Weistroffer (2009). Documentation in Systems Development: A Significant Criterion for Project Success.
[2] Forward (2002). Software Documentation — Building and Maintaining Artefacts of Communication.
[3] AltexSoft Inc (2018). Software Documentation Types and Best Practices
[4] Makoto Nakayama, Eli Hustad, Norma Sutcliffe (2021). Agility and system documentation in large-scale enterprise system projects: a knowledge management perspective
[5] Junji Zhi, Vahid Garousi-Yusifoğlu, Bo Sun, Golara Garousi, Shawn Shahnewaz, Guenther Ruhe (2015). Cost, benefits and quality of software development documentation: A systematic mapping
Autora Clarice Abreu é mulher, lésbica e engenheira de software. Com formação acadêmica em Sistemas de Informação pela Universidade de São Paulo, atualmente trabalha na Meta construindo ferramentas para o combate ao conteúdo nocivo e a usuários mal intencionados nas plataformas da empresa. É uma entusiasta da qualidade de software em todos os estágios de desenvolvimento e anseia por um mundo com mais mulheres na área de tecnologia. Revisora Stephanie Kim Abe é jornalista, formada pela Escola de Comunicações e Artes da Universidade de São Paulo (ECA-USP). Trabalha na área de Educação e no terceiro setor. Esteve nos primórdios da Programaria, mas testou as águas da programação e achou que não era a sua praia. Mas isso foi antes do curso Eu Programo…
Este conteúdo faz parte da PrograMaria Sprint Tech Leads.
O que você achou deste conteúdo? Deixe sua avaliação abaixo: