Erros comuns em documentos escritos por engenheiros e como corrigi-los

Nos últimos seis meses, nossa equipe de desenvolvimento adotou a abordagem "docs-as-code" (você pode aprender mais sobre nossa jornada neste artigo ). Revendo regularmente a documentação criada por meus colegas da Divisão de Tecnologia, compilei uma lista dos problemas mais comuns encontrados na redação de documentação técnica.

No artigo, mostrarei como corrigir esses problemas usando as ferramentas da abordagem “docs-as-code”.

Problema 1. “A redação de documentos não é de nossa responsabilidade”

Lidar com a documentação de forma ad hoc é como dar um tiro no próprio pé para toda a equipe de desenvolvimento. Se a equipe não tem capacidade, é um motivo convincente para tornar a manutenção da documentação mais previsível e voltada para a tecnologia.

Consertar:

• Integre a abordagem “docs-as-code” ao desenvolvimento da documentação. Dessa forma, você pode atualizar a documentação iterativamente, juntamente com a base de código, sem o risco de acumular dívidas técnicas.
• Desenvolva ou integre um espaço ou uma plataforma que possa renderizar documentos técnicos e servir como fonte única de informação.
• Utilize um ambiente de desenvolvimento integrado (IDE). Um IDE permite incorporar plug-ins e criar scripts personalizados para o desenvolvimento de documentação. IDEIA é uma excelente ferramenta para escrever documentos, mas você pode ter seus favoritos entre os aplicativos.
• Instale um plug-in de verificação ortográfica para evitar erros de digitação. Adicionar o plug-in ao seu IDE é um processo rápido e fácil.
• Adote as diretrizes internas especialmente elaboradas por sua empresa, levando em consideração as percepções da comunidade de redação técnica (se houver), para estabelecer uma abordagem padronizada para o desenvolvimento de documentação dentro da empresa. Seguir essas diretrizes simplificará o processo de documentação, economizando tempo ao contemplar o que e como escrever com precisão.
• Automatize as verificações com base nas diretrizes para reduzir ou eliminar significativamente o tempo de revisão de documentos.
• Modele tudo o que for possível e combine com a equipe a padronização dos componentes da documentação.

Oferecerei recursos valiosos que aumentarão sua confiança ao trabalhar com documentação técnica. Acredito que esses recursos são abrangentes o suficiente para equipá-lo para lidar com documentos técnicos de maneira eficaz:

• O " Guia de estilo da documentação do desenvolvedor do Google " serve como um manual abrangente para a documentação do desenvolvedor. Abrange tudo o que você precisa saber sobre formatação, pontuação, listagem e adição de blocos de código. Este guia é suficiente e tem sido uma referência valiosa para o desenvolvimento de nossas diretrizes internas, das quais tomamos emprestado algumas Melhores Práticas.
• “ Documentos para desenvolvedores " é um livro de leitura obrigatória para qualquer pessoa envolvida no trabalho com documentação de desenvolvedor, esteja desenvolvendo, escrevendo ou mantendo. O livro apresenta vários autores renomados e estimados no campo da redação técnica.

• " Código Docs Like " de Anne Gentle, uma escritora técnica, é um guia prático que mostra a cultura de documentação no OpenStack. Por meio de exemplos práticos, o autor explica por que a documentação deve ser gerenciada no GitHub e como implementar processos tecnológicos para uma documentação eficaz. O livro também oferece informações valiosas insights sobre como escrever documentação profissional, independentemente de você ser um desenvolvedor ou um redator técnico.

• Mencionarei também diretrizes internas para redação de documentação técnica, que devem incluir modelos e regras de formatação. Essas diretrizes existem em todas as empresas. Normalmente, eles são desenvolvidos em colaboração com um redator-pioneiro técnico e defensores de documentos de desenvolvimento e evoluem à medida que a cultura de documentação dentro da equipe cresce.

Problema 2. Escrever documentação sozinho

Desenvolver toda a documentação sozinho e, em seguida, enviá-la para revisão acarreta o risco de criar documentação redundante ou irrelevante que pode não estar alinhada com a finalidade pretendida.

Consertar:

• Sempre comece com um esboço e compartilhe-o com seu líder de equipe, proprietário do produto, redator técnico ou qualquer colega disposto a fornecer sua opinião especializada.
• Escreva passo a passo e atribua solicitações pull para revisão aos mesmos colegas mencionados acima.
• Colete e trabalhe com feedback.
• Considere os comentários. E vá com calma no tom de voz da revisão, às vezes pode ser duro, mas é apenas uma peculiaridade do processo de revisão.
• Não negligencie o fluxo de documentação. Segue abaixo o fluxo geral adotado em nossa empresa, mas as características deste fluxo podem depender tanto da equipe de desenvolvimento quanto da empresa:

Questão 3. “Quem precisa entender entenderá”

De vez em quando ouço das equipes: “estou escrevendo para a equipe de desenvolvimento”, “quem precisa entenderá”, “é assim que evoluiu historicamente dentro da nossa equipe”.

Mas o jargão profissional e os anglicismos exigem adequação e consistência. O uso excessivo deles pode levar a uma documentação semelhante às anotações de um engenheiro louco.

Para documentação, use as palavras e estruturas mais simples possíveis. Um dos principais princípios é escrever para rolar. A documentação pode ser difícil de escrever, pois geralmente é extensa, mas os leitores raramente a examinam de capa a capa. Em vez disso, eles tendem a rolar ou usar a pesquisa por palavra-chave. Portanto, o texto deve ser facilmente compreensível quando aberto de qualquer parte.

Consertar:

• Verifique os termos em inglês e o jargão profissional usando dicionários e normas atuais (ou simplesmente pesquise no Google). Se existir uma palavra no dicionário, escreva de acordo com as regras da ortografia do seu idioma.
• Se a palavra não estiver presente no idioma, escreva-a no idioma original e forneça uma tradução para o seu idioma entre parênteses.
• Adicione a palavra à seção do glossário e as abreviações à lista de abreviações e acrônimos. Isso é especialmente importante para abreviaturas "proprietárias" (não importa o quanto seja mencionado ou escrito sobre PO, seu significado ainda é uma das perguntas comuns ao ler a documentação).
• Consistência – atenha-se ao estilo de redação escolhido e às abreviações em toda a documentação (melhor para toda a documentação disponível em sua empresa).
• Planeje a navegação do documento com cuidado. Deve haver uma maneira rápida de encontrar a seção relevante sem ter que ler o documento inteiro. Portanto, é essencial estruturar cuidadosamente o conteúdo com títulos claros e concisos. Modelos de documentação interna devem ser desenvolvidos para simplicidade e conveniência.

Problema 4. Escrever documentação simultaneamente em vários lugares

Para a documentação, ter uma única fonte de verdade – um espaço onde você pode encontrar as informações necessárias sem se preocupar com sua precisão é crucial. Para nossa documentação técnica, uma plataforma desenvolvida internamente serve como tal espaço. Evitar a fragmentação da documentação em diferentes espaços é essencial para evitar que alguém seja enganado com informações desatualizadas.

Consertar:

• Antes de publicar documentação técnica em qualquer lugar, verifique se ela não existe em outro lugar, caso a empresa utilize vários espaços para compartilhamento de conhecimento.
• Arquive ou exclua (se você for proprietário) a documentação técnica desatualizada. Se você estiver preocupado com a exclusão prematura (por exemplo, devido a links externos para a página), adicione uma chamada informando que a página está desatualizada e o local atual da documentação de documentos válidos, onde atualizações adicionais devem ser feitas.
• Se você encontrar informações ou insights valiosos, adicione-os à documentação. Não deixe no Slack ou em qualquer outro lugar, principalmente em chats privados. Conhecimento que vale a pena compartilhar!

Enviado por Anna Goncharova