Nos últimos seis meses, nossa equipe de desenvolvimento adotou a abordagem "docs-as-code" (você pode aprender mais sobre nossa jornada neste
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
