Olá, Habr! Meu nome é Lesha, sou analista de sistemas de uma das equipes de produtos do Alfa-Bank. Agora estou desenvolvendo um novo banco online para pessoas jurídicas e empreendedores individuais.
E quando você é analista, principalmente nesse canal, você não chega a lugar nenhum sem documentação e trabalho próximo com ela. E documentação é algo que sempre levanta muitas dúvidas. Por que o aplicativo da web não está descrito? Por que a especificação indica como o serviço deve funcionar, mas não funciona assim? Por que é que apenas duas pessoas, uma das quais a escreveu, conseguem compreender a especificação?
No entanto, a documentação não pode ser ignorada por razões óbvias. E para facilitar a nossa vida, decidimos avaliar a qualidade da documentação. Como exatamente fizemos isso e a que conclusões chegamos está abaixo do limite.
Qualidade da documentação
Para não repetir “Novo Internet Bank” várias dezenas de vezes no texto, escreverei NIB. Agora contamos com mais de uma dezena de equipes trabalhando no desenvolvimento do NIB para empreendedores e pessoas jurídicas. Além disso, cada um deles cria sua própria documentação para um novo serviço ou aplicativo web do zero ou faz alterações no atual. Com esta abordagem, a documentação pode, em princípio, ser de alta qualidade?
E para determinar a qualidade da documentação, identificamos três características principais.
- Deve estar completo. Isso soa como um capitão, mas é importante observar. Deve descrever detalhadamente todos os elementos da solução implementada.
- Deve ser atual. Ou seja, correspondem à implementação atual da própria solução.
- Deve ser compreensível. Para que quem o utiliza entenda exatamente como a solução é implementada.
Para resumir - documentação completa, atualizada e compreensível.
Опрос
Para avaliar a qualidade da documentação, decidimos entrevistar quem trabalha diretamente com ela: os analistas do NIB. Os entrevistados foram solicitados a avaliar 10 afirmações de acordo com o esquema “Em uma escala de 1 a 5 (discordo totalmente - concordo totalmente)”.
As declarações refletiram as características da documentação qualitativa e a opinião dos compiladores da pesquisa em relação aos documentos do NIB.
- A documentação das aplicações NIB está atualizada e totalmente consistente com a sua implementação.
- A implementação de aplicações NIB está totalmente documentada.
- A documentação para aplicações NIB é necessária apenas para suporte funcional.
- A documentação das aplicações NIB está atualizada no momento da sua submissão para suporte funcional.
- Os desenvolvedores de aplicativos NIB usam a documentação para entender o que precisam implementar.
- Existe documentação suficiente para as aplicações NIB compreenderem como são implementadas.
- Atualizo prontamente a documentação dos projetos NIB se eles forem finalizados (pela minha equipe).
- Os desenvolvedores de aplicativos NIB revisam a documentação.
- Tenho uma compreensão clara de como preparar documentação para projetos NIB.
- Eu entendo quando escrever/atualizar documentação para projetos NIB.
É claro que simplesmente responder “De 1 a 5” pode não revelar os detalhes necessários, portanto uma pessoa pode deixar um comentário sobre cada item.
Fizemos tudo isso por meio do Slack corporativo: simplesmente enviamos um convite aos analistas de sistemas para responderem a uma pesquisa. Eram 15 analistas (9 de Moscou e 6 de São Petersburgo). Após a conclusão da pesquisa, geramos uma pontuação média para cada uma das 10 afirmações, que então padronizamos.
Acontece que é o que.
O inquérito mostrou que, embora os analistas estejam inclinados a acreditar que a implementação de aplicações NIB está totalmente documentada, não dão um acordo inequívoco (0.2). Como exemplo específico, salientaram que uma série de bases de dados e filas de soluções existentes não estavam cobertas pela documentação. O desenvolvedor consegue dizer ao analista que nem tudo está documentado. Mas a tese de que os desenvolvedores revisam a documentação também não recebeu apoio inequívoco (0.33). Ou seja, permanece o risco de descrição incompleta das soluções implementadas.
A relevância é mais fácil – embora novamente não haja um acordo claro (0,13), os analistas ainda estão inclinados a considerar a documentação relevante. Os comentários permitiram compreender que os problemas de relevância estão mais frequentemente na frente do que no meio. No entanto, eles não nos escreveram nada sobre apoio.
Quanto a saber se os próprios analistas entendem quando é necessário redigir e atualizar documentação, o acordo foi bem mais uniforme (1,33), inclusive no seu desenho (1.07). O que foi apontado aqui como inconveniente foi a falta de regras uniformes para a manutenção da documentação. Portanto, para não ativar o modo “Quem vai para a floresta, quem pega lenha”, eles têm que trabalhar com base em exemplos de documentação existente. Portanto, um desejo útil é criar um padrão para gerenciamento de documentos e desenvolver modelos para suas peças.
A documentação para aplicações NIB está atualizada no momento da submissão para suporte funcional (0.73). Isso é compreensível, pois um dos critérios para submeter um projeto para suporte funcional é a documentação atualizada. Também é suficiente compreender a implementação (0.67), embora por vezes permaneçam dúvidas.
Mas o que os inquiridos não concordaram (de forma bastante unânime) foi que a documentação para aplicações NIB, em princípio, só é necessária para suporte funcional (-1.53). Os analistas foram mencionados com mais frequência como consumidores de documentação. O resto da equipe (desenvolvedores) - com muito menos frequência. Além disso, os analistas acreditam que os desenvolvedores não utilizam a documentação para entender o que precisam implementar, embora não de forma unânime (-0.06). A propósito, isso também é esperado em condições em que o desenvolvimento do código e a escrita da documentação ocorrem em paralelo.
Qual é o resultado final e por que precisamos desses números?
Para melhorar a qualidade dos documentos, decidimos fazer o seguinte:
- Peça ao desenvolvedor para revisar os documentos escritos.
- Se possível, atualize a documentação em tempo hábil, primeiro.
- Crie e adote um padrão para documentar projetos NIB para que todos possam entender rapidamente quais elementos do sistema e como exatamente devem ser descritos. Bem, desenvolva modelos apropriados.
Tudo isto deverá ajudar a elevar a qualidade dos documentos a um novo nível.
Pelo menos eu espero que sim.
Fonte: habr.com