Como melhorar a documentação do time

Um ponto bem importante de discussão que tive com o meu time no final do ano passado foi sobre a importância de considerarmos os cards do Jira como documentação oficial do time. Mas se engana quem pensa que apenas a criação do card é a etapa mais importante dessa documentação.

Quando temos um card avançando no quadro do Jira, as atualizações que acontecem no desenvolvimento devem ser documentadas no card. Mas, de nada importa cobrarmos do PM uma boa escrita de descrição no card, se não fazemos a nossa parte de registrar as evoluções de forma coerente e clara.

Importância de atualizar os cards

Para ficar mais claro o meu ponto, vou listar aqui as três principais razões pelas quais considero importante manter os cards atualizados.

A primeira razão é a clareza do que está em produção. Se o card descreve o que deve ser desenvolvido e essa definição muda ao longo do caminho, é importante deixar claro o que mudou e o motivo da mudança. Se futuramente for preciso consultar alguma mudança de regra de negócio, não vamos depender da memória do time para entender o que mudou.

A segunda razão é o histórico para os próprios desenvolvedores. Quando alguém vai alterar alguma parte do sistema, apenas o código pode não ser suficiente para entender o estado atual. Ter um card descrevendo o que foi mudado e a motivação da mudança facilita muito no entendimento de demandas mais complexas. Além de ser útil para desenvolvedores atuais no time, também pode ser muito útil para novos desenvolvedores, que conseguem entender o que foi desenvolvido de forma independente.

A terceira razão é para me ajudar a montar as Operation Reviews do time. Por exemplo, sempre que um card é bloqueado, eu peço para o time colocar o motivo do bloqueio nos comentários. Como já mencionei em outro post, as métricas por si só não refletem tudo o que aconteceu com um card e precisamos de contexto. Um card bloqueado sempre vai ter uma elevação no Cycle Time e não ter uma justificativa do bloqueio impede uma análise mais realista do que foi desenvolvido. Consequentemente, eu não terei o contexto completo para explicar o desempenho do time na Operation Review.

É comum todos acharem que vão lembrar do que foi discutido e das mudanças que aconteceram. Até o momento em que alguém questiona uma regra de negócio de 6 meses atrás e ninguém sabe o que aconteceu. Só isso já poderia resumir a importância da documentação.

5W2H

A minha orientação para o time é que considerem o formato 5W2H no momento de escrever um comentário para conferir se ele está completo:

• What (O quê?): o que foi feito?
• Why (Por quê?): por que foi feito?
• Who (Quem?): quem foi responsável por fazer a ação?
• Where (Onde?): onde a ação foi realizada?
• When (Quando?): quando a ação foi ou será realizada?
• How (Como?): como a ação será feita?
• How much (Quanto?): quanto custará a execução da ação?

Se depois de escrever o seu comentário, você reler o que está escrito e não conseguir responder à maioria dessas perguntas, provavelmente o seu comentário está incompleto e insuficiente para servir como documentação.

É sempre importante pensar que quem está lendo o teu comentário não vai ter o contexto completo e frases soltas não vão deixar claro o que aconteceu. Talvez você mesmo no futuro não lembre do contexto em que a mudança aconteceu e se arrependa de não ter dado mais detalhes quando estava com as informações frescas na cabeça.

Não é preciso responder todas essas perguntas em todos os comentários, porque algumas delas já podem estar sendo respondidas na descrição do card. Mas é sempre bom avaliar todas elas para entender quais são indispensáveis para um bom entendimento.

Gosto de discutir esses temas com o time porque é importante compartilhar responsabilidades. Por mais que eu goste de manter as documentações sempre atualizadas, fica quase impossível manter tudo certo quando decido fazer tudo sozinha num time de 8 pessoas.

Caso nunca tenhas se atentado a isso, recomendo que prestes mais atenção nos cards e no quanto eles estão refletindo o que realmente aconteceu até o código chegar em produção. Certamente você vai evitar muitos problemas no futuro seguindo essa boa prática.

Até a próxima!

Copiar link