Cultura de documentação para escalar times
Tags: beginners, productivity, devrel, career
Published: 2022-11-30 12:43:52

Pensar na documentação como forma de escalar times é algo que vem dominando rodas de conversas de muitas empresas. 

Nesse cenário, um trabalho a ser feito é na conscientização de quem quer evoluir na carreira.

A criação da cultura da documentação passa pela necessidade investir tempo para documentar processos que estão sobre o conhecimento das pessoas mais experientes e que poderiam virar uma simples wiki no GitHub.

Documentação em formato wiki tem ganhado força pela simplicidade de escrita com markdown. As pessoas desenvolvedoras possuem familiaridade com a ferramenta via Github e pessoas não desenvolvedora tem curva de aprendizado bem curta.

Quando se trata de adotar modelos que já estão sendo testado por diversas empresas, a experiência nos mostra que escolher um e testar, na maioria da vezes atendem as particularidades do negócio e as vezes apenas com poucas alterações.

A resposta sobre o "por que precisamos documentar", pode ser a chave para iniciar o processo de construção dessa cultura. 

Nas comunidades de tecnologia a muito tempo compartilhamos, com quem deseja fazer mentoria, que a primeira tarefa a se fazer é automatizar respostas das perguntas mais frequentes, assim as consultas nas redes sociais, são direcionadas para postagens ou respondidas com copia-e-cola que já sabemos ser dúvidas recorrente.

Todos nós envolvidos com produtos de tecnologia precisamos desenvolver formas de deixar nossas anotações a disposição de novos aprendizes.

Por que as pessoas mais experientes, na maioria das vezes, não dedica tempo para essa tarefa?

Mas ser consultado a todo momento não é bom? Ser fonte de informação não mostra que tenho algum valor?

Não, mostra só que você está cheio de atividades e que essas tarefas poderiam ser uma wiki de fácil acesso ao time.

Se você tiver mais tempo livre poderá se dedicar a novos assuntos ou a temas que façam sua carreira evoluir ainda mais rápido.

Toda vez que investimos tempo fazendo uma documentação, significa que as próximas consultas vão nos demandar menos tempo de dedicação para a nossa resposta e será de forma assíncrona, assim nós abrimos espaço valioso em nossas agendas pessoais ou profissionais.

Já pensou sobre aquele aprendizado que gostaria de se dedicar mad que não encontra tempo, quem sabe essa não seja uma forma de encontrar espaço na sua agenda?!

Em alguns tipos documentação, a pessoa que está consultando é quem vai fazer a atualização, suas dúvidas, tentativas e erros, trará as correções necessárias na documentação, um exemplo que presenciei recentemente foi na mudanças na documentação do Docker, onde uma mudança no script externo, alterou o setup dos projetos da empresa e isso forçou uma atualização por parte do usuário, apoiado nos times para a validação.

Quando falamos de documentação as pessoas logo pensam em páginas e páginas, e não é sobre isso, a documentação na maioria das vezes pode ser um Read-me bem feito, a motivação de uma Issue bem escrita, um PR bem descritivo, um como testar adequado, ou um template que facilite os primeiros passos são itens corriqueiros do dia a dia que deixamos de lado.

Quando falamos de times que estão em crescimento esse gargalo vai ficando cada vez mais evidente, isso acontece quando fazer a tarefa passa a ser mais rápida do que explicar para alguém como se faz. Aqui a roda da perversidade em tecnologia começa a girar, pois o sênior fica responsável por muitas tarefas e os mais novos ficam sem a orientação adequada, levando todos a um desgaste emocional muito alto e é um ciclo não sustentável a longo prazo.

Ainda não o sabe por onde começar a documentação?

Pode ser organizando e disponibilizando suas anotações de forma pública no seu time.

Estimule a cultura de documentação já no inicio das tarefas, uma tarefa sem documentação não deveria ser considerada entregue. Existem exceções a regra, mas o time todo precisa está de acordo com isso.

Um dos melhores momentos para se começar uma documentação são nas cerimônias de refinamentos.

Já perceberam o quanto os refinamentos dependem de algumas pessoas? 

Já perceberam que a maioria dos Spikes nascem nos refinamentos? E por "by the book" já deveriam ter documentação com parte do processo.

E as POCs? Observem como esse processo é um momento de descobertas e que poderiam serem inclusas documentação como parte do entregável?

Não caia na ilusão de que times maduros não precisam ter processos escritos, essa é a porta de entrada para não inovar, pois só quem já está no time detém o conhecimento e isso impede a chegada de novos desenvolvedores, e cria silos de conhecimentos.

Inclua nos critérios de aceite a documentação minima, ou atualização dela, as vezes apenas o racional dos motivos pelo qual foi considerada cada decisão já vai ajudar muito quem vier a ler essa issue ou PR.

Em um dos times que trabalhei na Vindi, nós tínhamos na coluna do Kanban, nas descrições a seguinte pergunta:

"Precisa escrever ou alterar a documentação?"

Sem responder essa questão não podíamos mover o card para a coluna revisão.

Existem diversas ferramentas para documentar nossos códigos, ou criar gestão de conhecimento nas empresas, em muitas conversas, pesquisas, videos e participação em meetups, conseguimos observar que o melhor é usar um recurso que o Devs já usam para em suas tarefas, isso evita que eles tenham que mudar de ambiente para documentar, ajuda a criar uma cultura forte e evita resistência ao processo. Quando já se tem uma cultura de documentação, mesmo que descentralizada, outras ferramentas como confluence, notion, ou CMS podem ajudar os times não técnicos a conseguirem de forma eficiente o que procuram.

Documentação é inspiração, e inspiração vem de pessoas para pessoas. 

Os responsáveis por reforçar essa cultura são os mais experientes, são eles que detêm maior conhecimento e o super poder do compartilhamento.

As lideranças precisam zelar por um ambiente seguro, onde as pessoas possam se expressar, permitir a espontaneidade e voluntarismo faz com que a motivação das pessoas floresçam, só assim a inovação aparece. 

É preciso permitir o erro, nós vamos errar, a documentação é viva, precisa ser de fácil leitura, e a sua escrita é para conseguir a compreensão de quem não tem a mesma experiencia que a nossa.

Alguns links sobre documentação que eu já fiz por ai:

[Documentação de software: por que é importante e como fazer?](https://blog.vindi.com.br/documentacao-de-software/)

[Como consultar um especialista](https://dev.to/biosbug/como-consutar-um-especialista-2jhp)

[Jovens, documente!](https://dev.to/biosbug/jovens-documente-3093)

[O que voce ensinou para o seu Senior hoje](https://dev.to/biosbug/o-que-voce-ensinou-pro-seu-senior-hoje-3jp)