Derrotando o monstro da documentação assustadora

Kristiina Ritso Blocked Unblock Seguir Seguindo 9 de janeiro

"Ei! Você pode escrever essa documentação do usuário final sobre o aplicativo que estamos desenvolvendo? ”-“ Eu vou chegar a isso quando tiver tempo. ”

Já teve esse tipo de conversa e nunca realmente acabou de escrever a maldita coisa porque alguma outra tarefa de maior prioridade surgiu? Tudo é ágil, movendo-se rapidamente e os recursos obtêm o foco. Como a documentação pode trazer valor quando é frequentemente considerada desperdício?

Em nossas vidas, todos entramos em contato com alguma forma de documentação, sejam requisitos técnicos, especificações da API, receitas, jogos de tabuleiro ou manuais de montagem de móveis. Nós os achamos úteis e reconfortantes, mesmo que nunca os leiamos mais de uma vez. Um dos principais pontos do desenvolvimento ágil de software é produzir software, não documentação. O que acontece quando as coisas ficam muito extremas e você acaba numa situação em que não há documentação alguma ou muito pouco disso? Bem, nós estávamos lá.

A documentação pode desempenhar um papel enorme. Isso pode afetar os desenvolvedores quando eles precisam retornar a um projeto que está em uma prateleira há anos ou a bordo de um novo membro da equipe. Pode ser um risco significativo para o cliente quando o produto tem que ser entregue, e eles começam a mantê-lo por conta própria. Sem um conjunto adequado de documentação mínima viável, pode se tornar mais caro do que escrevê-lo em primeiro lugar. Infelizmente, quando chegou a hora de começar, as prioridades foram estabelecidas em diferentes aspectos do processo de desenvolvimento. Muitas vezes é o orçamento que define os limites porque o valor nem sempre é visível ou chega tarde demais. Então, como podemos torná-lo valioso para todos sem colocar um grande buraco em nosso orçamento?

Etapas iniciais: integrando um membro da equipe

Existem muitos projetos em nosso cofre de desenvolvimento. Alguns deles bem documentados, alguns têm uma linha ou duas escritas no arquivo README, e alguns têm informações espalhadas em todos os tipos de canais de comunicação. Escrever documentação parecia ser como lutar contra um monstro. Alguns aceitaram o desafio apenas para descobrir que não era tão assustador. Outros decidiram deixar alguém lidar com isso. Queríamos torná-lo menos intimidante e transformá-lo em uma parte natural do processo. Para isso, tivemos que começar do começo.

Vimos pela primeira vez lugares para melhorias quando tivemos que incorporar um novo desenvolvedor à equipe. Nosso desafio era encontrar uma maneira de comunicar o processo de desenvolvimento da maneira mais eficiente possível e fornecer uma fonte para a nova pessoa voltar. Criamos um modelo para os membros da equipe preencherem, listando todas as informações relacionadas ao desenvolvimento e o fluxo de trabalho da equipe. Esse modelo ajudou os desenvolvedores iniciais a não perder nenhuma informação vital e deu ao novo membro da equipe um lugar para voltar quando precisassem. Felizmente, ocorreu uma situação perfeita. Dois projetos trocaram desenvolvedores. Isso nos deu um excelente campo de teste para o modelo para validar a solução. Os desenvolvedores preencheram o documento e realizaram o processo de integração entre si. Imediatamente pudemos obter feedback e revisar o modelo. Com um pouco de esforço e sorte do nosso lado, já tínhamos um sólido ponto de partida.

Ok, mas isso só resolve um problema – ter documentação para integração. Ainda faltava documentação para projetos de menor escala e o hábito de criá-lo.

Avançando

Nós tínhamos feito o nosso quinhão de apenas-se e what-if, se queimou de erros do passado e lambeu nossas feridas. Agora era hora de agir para que pudéssemos melhorar.

Para sistemas e projetos maiores, temos documentação suficiente. Isso faz parte do nosso processo que começa com a elaboração de arquitetura e análise de requisitos. Para projetos de menor escala, essas fases são mais curtas e, portanto, nem sempre produzem documentação suficiente.

A partir do modelo de integração, encontramos uma maneira de gerar um ponto de partida para o ReadMe do projeto. Existem muitos exemplos de ReadMe-s disponíveis, mas precisávamos de algo personalizado para os processos de nossa empresa. Começamos com a definição dos papéis nas fases de desenvolvimento. O mapeamento de todas as partes ajuda a identificar informações comuns necessárias. Depois de mapeados, também analisamos com mais profundidade o interesse dessas partes. Por exemplo, não é necessário que o designer conheça todas as restrições técnicas, mas está interessado em saber onde encontrar o aplicativo. e quem contatar quando tiverem dúvidas. Como pretendíamos manter as informações suficientes, mas mínimas, filtramos os aspectos mais críticos desses valores compartilhados.

Também precisávamos encontrar uma maneira de torná-lo facilmente acessível e atualizável. Sem ter um bom hábito de escrever documentação ou mantê-la atualizada, é difícil motivar-se. Achamos mais confortável incluí-lo como parte de uma tarefa de desenvolvimento. Incluir documentação como parte da definição de feito parecia o mais fácil. Ajuda a criar um hábito e torná-lo uma parte natural do ciclo de vida de uma tarefa. Isso ajuda a manter o processo de documentação ágil. Com pouco esforço, temos uma maneira de manter as informações atualizadas e relevantes sem produzir desperdício.

Depois de várias sessões, finalmente tivemos um modelo para incluir em nossos projetos que foram estruturados e não é um assustador Monster de Documentação para preencher, dando-nos um trampolim para melhorar ainda mais e ver a importância da documentação bem antes, quando ela é realmente necessária.

Principais tópicos

Como no mundo ágil, ainda estamos nos movendo com as correntes e melhorando o processo, mas estamos em um lugar muito melhor do que há algum tempo. Sem descartar os princípios da metodologia ágil, chegamos a um processo de documentação que é enxuto e eficaz. Mantém seu valor sendo atualizado quando há necessidade.

O que nós aprendemos:

  • Comece a escrever a documentação de entrega o mais cedo possível
    Ao lidar com um projeto pequeno, mantenha a documentação eficiente e deixe-a crescer com o projeto.
  • Continue escrevendo a documentação como parte da definição do problema do feito, em vez de uma tarefa separada. Desta forma, você terá um processo de documentação ágil
  • O desenvolvimento de modelos para determinados tipos de documentação fará com que o processo pareça menos assustador.

Deixe-nos saber na seção de comentários que monstros documentação você enfrentou e como você enfrentá-los?