Porque o código sem uma documentação clara pode matar um projeto ou produto, e o que o Tecnical writing tem a ver com isso.

Quando se trata de tecnologia, a documentação é muito importante. Isso se aplica a qualquer tipo de código, seja ele de um software, de um site ou de um aplicativo.

De forma bem poética, a documentação de código coesa e consistente se baseia em um documento que tem a missão de guiar de maneira lógica e de fácil entendimento para seja la quem for usá-lo.

Mas por que documentar o código? Primeiro, para tornar o projeto mais acessível e compreensível, seja para seu time, sua squad ou sua tribo. Se você tiver um código bem documentado, qualquer pessoa conseguirá usá-lo para com propósito, mesmo que não seja uma pessoa programadora profissional.

Além disso, a documentação também é muito útil para quem o criou. É comum que, depois de algum tempo, as pessoas esqueçam detalhes sobre o código quando não o usam por um tempo. A documentação serve como um lembrete, para que você possa voltar e ver o que fez e como fez.

Existem muitas maneiras de documentar um código, mas a forma mais comum é através de comentários. Os comentários são linhas de texto que são ignoradas pelo compilador, mas que podem ser lidas por nos. Eles são úteis para explicar o que um trecho de código faz, sua utilidade e funcionamento.

Além dos comentários, a documentação pode incluir coisas como diagramas e fluxogramas. Esses materiais costumam ajudar a explicar o seu funcionamento de uma maneira mais visual, o que pode ser útil para aqueles que não estao familiarizados com a tecnologia ou a arquitetura do projeto.

Exemplo de fluxograma e diagrama que podem compor uma documentação de software

E a documentação também ajuda a manter o código atualizado. Se houver alguma mudança, uma nova versão precisar ser informada a todos que forem usar o código.

Embora a documentação de código seja importante, o processo pode ser tedioso para devs que acabam não se dedicando, seja por falta de tempo ou alinhamento, trazendo muitos problemas para o projeto como por exemplo a sua descontinuação (leia morte) e consequentemente danos materiais a empresa.

Em razão desse gap (estou falando no mundo todo) surgiu a carreira de Tech Writing com a proposta de otimizar, padronizar e escalar o conhecimento técnico de uma empresa. Essa nova profissão esta expandindo para a felicidade geral da TI, oferecendo oportunidades em grandes empresas.

Mas o que a pessoa Technical Writing faz? De forma simples: não deixa o código morrer e assim nao deixando o samba do projeto acabar.

E pode conter no seu escopo de trabalho: produção de conteúdos técnicos para orientar o usuário, como a criação de manuais ou instruções e outros materiais para desenvolvimento de softwares.

Como foi explicado no início do artigo, o conteúdo precisa ser claro, conciso e objetivo para que o usuário, incluindo o ecossistema de desenvolvimento, consiga saber melhor sobre o produto.

É uma carreira que exige um olhar muito atento a experiência do usuário e voltado a pessoas que querem aprimorar seu conhecimento técnico sem precisar se dedicar à escrita do código de fato. E sua existência nao busca exonerar a pessoa desenvolvedora de documentar o seu código, na verdade sao aliadas no registro inteligente durante a construção de novas tecnologias.

Para quem está interessado na carreira de Tech Writing, a Mari Moreira é referência no Brasil sobre o assunto. Faz parte de comunidade dedicada a carreira e criou um curso online que ensina todas as técnicas necessárias para se tornar um expert na área. Clique aqui e confira!

Espero ter despertado em você, duas coisas mínimas:

1 — Entendimento sobre a relevância e o impacto que uma boa documentação pode ter na sua carreira developer.

2 — A descoberta de uma carreira, ainda dentro de TI, que pode brilhar aos olhos, caso pense em migrar de carreira.

E esse foi o meu primeiro artigo. Estou experimentando algumas formas de escrita usando um vocabulário simples, humanizada e sem o abuso de jargões técnicos.

Gostou? deixe seu feedback aqui, curta e compartilhe para pessoas que possam se interessar nesse assunto.