A documentação da sua empresa provavelmente está faltando de várias maneiras, mas com apenas um pouco de trabalho e orientação, seus desenvolvedores podem levá-la para o próximo nível.
Se seus desenvolvedores, designers, administradores e membros da equipe não documentam seu trabalho, seu negócio não está funcionando tão bem quanto poderia. Simplificando, esforços sólidos de documentação podem realmente ajudar a melhorar o fluxo de trabalho e a confiabilidade dos seus processos. Uma boa documentação não apenas evita lacunas na compreensão de como algo funciona, mas também torna muito mais fácil para qualquer pessoa assumir uma função e ser eficaz.
O problema é que uma documentação ruim pode ser pior do que nenhuma documentação. Quando a documentação é mal escrita, pode ser difícil usá-la e pode confundir os membros da equipe a ponto de nada poder ser feito até que aquele tópico específico seja desvendado.
E a documentação não se aplica apenas aos desenvolvedores. A documentação pode ser usada para qualquer coisa dentro da sua empresa, como:
- Como usar software
- Como usar hardware
- Qualquer fluxo de trabalho
- Melhores práticas gerais
- Integração da equipe
- RH e pessoal
Embora a documentação possa levar algum tempo, o esforço vale a pena, pois sua empresa economizará um tempo considerável no longo prazo, além de evitar confusões e obstáculos no futuro.
Dito isso, como seus desenvolvedores podem melhorar sua documentação? Vamos dar uma olhada em algumas idéias.
Desenvolva políticas de documentação
Esta deve ser a primeira coisa a fazer para melhorar a documentação. Não importa se você está apenas começando esta jornada desde o início ou está assumindo a tarefa de melhorar toda a sua documentação existente: reserve um tempo para desenvolver políticas para o processo e os resultados finais.
Para essas políticas, você precisará decidir o que está incluído na documentação, seu público-alvo, as ferramentas de documentação preferidas, a função dos comentários, se a documentação será hospedada em um sistema de controle de versão (como o Git) e se a documentação será aderir a um guia de estilo específico.
Depois de desenvolver essas políticas, certifique-se de que toda a documentação as siga à risca.
Use voz ativa
Em nome da criação de documentação sucinta e fácil de seguir, seus desenvolvedores precisam entender como usar a voz ativa. O oposto da voz ativa é a voz passiva e reduz drasticamente a clareza, consistência e eficiência.
Um exemplo simples de voz ativa versus voz passiva é assim:
- Voz ativa – Bob correu uma maratona.
- Voz passiva – Uma maratona foi disputada por Bob.
Ao usar a voz ativa, o sujeito realiza a ação (Bob correu uma maratona). Quando você usa a voz passiva, o sujeito sofre ação (uma maratona foi disputada por Bob).
Você deseja que cada frase da sua documentação seja o mais clara e simples possível. Não complique as coisas e não faça com que o leitor da documentação tenha que se esforçar para ter clareza.
Incentive o uso de títulos cativantes
Uma boa documentação deve ser considerada no mesmo nível que escrever qualquer tipo de conteúdo. Você deseja usar títulos atraentes para que o leitor saiba exatamente o que se segue e o que esperar. Isto é especialmente verdade, considerando como todos, em todos os lugares, vivem sob uma avalanche de conteúdo. Por causa disso, os usuários tendem a folhear muito mais do que antes. Quando você usa títulos (e subtítulos) atraentes, o conteúdo fica muito mais fácil de ler e absorver.
Qualquer coisa que você possa fazer para aliviar o fardo daqueles que dependem de documentação deve ser considerado obrigatório.
Deixe os chavões e siglas para trás
Ao adotar o uso de títulos cativantes, evite depender de chavões. Isto é especialmente importante em tecnologia porque nem todos entendem todas as palavras da moda e siglas.
Ao escrever documentação, é importante abordá-la como se quem está lendo não estivesse por dentro e não estivesse familiarizado com a linguagem atual. A documentação existe para ajudar outras pessoas a entender como sua empresa faz e usa algo. Se seus desenvolvedores se basearem demais em chavões e siglas, não há garantia de que aqueles que lerem os documentos compreenderão o que leram.
Adicionar recursos visuais
Sempre que possível, adicione recursos visuais à documentação. Isso é especialmente importante quando você documenta como uma ferramenta GUI funciona. Em vez de descrever um elemento gráfico, mostre uma imagem. Afinal, dizem que uma imagem vale mais que mil palavras e, no âmbito da documentação, esse ditado é verdadeiro.
Crie e use modelos
Uma coisa que você pode fazer para tornar todo esse processo exponencialmente mais fácil é criar modelos de documentação para seus desenvolvedores usarem. Isso reduzirá drasticamente o trabalho que eles terão que fazer porque terão um documento simples para orientá-los na criação de sua documentação.
Ao criar esses modelos, certifique-se de adicionar a eles quaisquer informações que não apenas garantam que sua documentação permaneça consistente, mas que tornem o conteúdo final mais fácil de criar. Considere este o seu meio de orientar seus desenvolvedores durante o processo de documentação. Quanto mais fácil você tornar isso para eles, maior será a probabilidade de eles realmente escreverem a documentação e seu trabalho seguirá suas diretrizes e será simples de usar.
Conclusão
A elaboração de documentação sólida deve ser colocada no topo ou próximo a ela de sua lista de coisas que são importantes para a eficiência de sua empresa. Com um processo de documentação sólido implementado, tudo correrá mais tranquilo. Não apenas seus desenvolvedores terão mais facilidade para criar documentação, mas aqueles que dependem da documentação também não terão que se esforçar para decifrar o significado ou a intenção do que estão lendo.
