Olá Habr! Meu nome é Lesha, sou analista de sistemas em uma das equipes de produtos do Alfa-Bank. Agora estou desenvolvendo um novo banco na Internet para pessoas jurídicas e empreendedores individuais.
E quando você é analista, especialmente em um canal assim, sem documentação e trabalho duro com ele - em nenhum lugar. E a documentação é o que sempre levanta muitas perguntas. Por que o aplicativo Web não está descrito? Por que a especificação indica como o serviço deve funcionar, mas não funciona? Por que apenas duas pessoas podem entender a especificação, uma das quais a escreveu?
No entanto, a documentação não pode ser ignorada por razões óbvias. E, para simplificar nossas vidas, decidimos avaliar a qualidade da documentação. Como exatamente fizemos isso e a que conclusões chegamos - sob o corte.
Qualidade da documentação
Para não repetir o texto “New Internet Bank” várias dezenas de vezes, escreverei o NIB. Agora, temos mais de uma dúzia de equipes trabalhando no desenvolvimento do NIB para empreendedores e pessoas jurídicas. Além disso, cada um deles, do zero, cria sua própria documentação para um novo serviço ou aplicativo da Web ou faz alterações no atual. Com essa 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. Parece muito capitão, mas é importante notar. Ele deve descrever em detalhes todos os elementos da solução implementada.
- Deve ser relevante. Ou seja, corresponde à implementação atual da própria solução.
- Deve ficar claro. Para que a pessoa que o utiliza entenda como a solução é implementada.
Resumindo - documentação completa, relevante e compreensível.
Enquete
Para avaliar a qualidade da documentação, decidimos entrevistar aqueles que trabalham diretamente com ela: analistas de NIB. Solicitou-se aos entrevistados que classificassem 10 declarações de acordo com o esquema "Em uma escala de 1 a 5 (discordo completamente - concordo completamente)".
As alegações refletiram as características da documentação de qualidade e a opinião dos compiladores da pesquisa sobre os documentos do NIB.
- A documentação sobre aplicativos NIB é relevante e totalmente consistente com sua implementação.
- A implementação dos aplicativos NIB está totalmente documentada.
- A documentação em aplicativos NIB é necessária apenas para suporte funcional.
- A documentação sobre aplicativos NIB é relevante no momento de seu envio para suporte funcional.
- Os desenvolvedores de aplicativos NIB usam a documentação para entender o que eles precisam implementar.
- A documentação para os aplicativos NIB é suficiente para entender como eles são implementados.
- Atualizarei a documentação dos projetos NIB em tempo hábil, se eles forem finalizados (pela minha equipe).
- Os desenvolvedores de aplicativos NIB revisam a documentação.
- Eu tenho um entendimento claro de como documentar projetos de NIB.
- Entendo quando escrever / atualizar a documentação em projetos NIB.
É claro que simplesmente a resposta “De 1 a 5” não pode revelar os detalhes necessários, para que uma pessoa possa deixar um comentário sobre cada item.
Fizemos tudo isso através do Slack corporativo - simplesmente enviamos uma proposta aos analistas de sistemas para responder à pesquisa. Havia 15 analistas (9 de Moscou e 6 de São Petersburgo). Após a conclusão da pesquisa, formamos uma classificação média para cada uma das 10 afirmações, que foi normalizada.
Foi o que aconteceu.
A pesquisa mostrou que, embora os analistas tendam a acreditar que a implementação dos aplicativos de NIB esteja totalmente documentada, eles não dão consentimento inequívoco (0,2). Como um exemplo concreto, eles indicaram que vários bancos de dados e filas de soluções existentes não foram cobertos pela documentação. O desenvolvedor é capaz de dizer ao analista que nem tudo está documentado. Mas a tese de que os desenvolvedores realizam uma revisão da documentação também não recebeu suporte inequívoco (0,33). Ou seja, o risco de descrições incompletas das soluções implementadas permanece.
É mais fácil com relevância - embora não haja acordo inequívoco novamente (0,13), os analistas ainda estão inclinados a considerar a documentação relevante. Os comentários nos permitiram entender que, com mais frequência, há problemas relevantes na frente do que no meio. É verdade que eles não escreveram nada sobre apoio.
Quanto ao fato de os próprios analistas entenderem quando escrever e atualizar a documentação, o acordo já era muito mais uniforme (1,33), incluindo seu design (1,07). O que foi apontado como um inconveniente aqui é a falta de regras uniformes para manter a documentação. Portanto, para não incluir o regime “Quem está na floresta, quem é a lenha”, eles precisam trabalhar com base em exemplos de documentação existente. Daí um desejo útil - criar um padrão para a manutenção de documentos, desenvolver modelos para suas partes.
A documentação sobre aplicativos NIB é relevante no momento da entrega para suporte funcional (0,73). É compreensível, porque um dos critérios para a entrega de um projeto ao suporte funcional é a documentação atualizada. Também é suficiente entender a implementação (0,67), embora algumas vezes permaneçam dúvidas.
Mas o que os entrevistados não concordaram (por unanimidade) é que a documentação sobre aplicativos NIB, em princípio, é necessária apenas para suporte funcional (-1,53). Analistas como consumidores de documentação foram mencionados com mais frequência. Os demais membros da equipe (desenvolvedores) - com muito menos frequência. Além disso, os analistas acreditam que os desenvolvedores não usam a documentação para entender o que precisam implementar, embora não por unanimidade (-0,06). A propósito, isso também é esperado em condições em que o desenvolvimento de código e a documentação de gravação são paralelos.
Qual é o resultado e por que precisamos desses números
Para melhorar a qualidade dos documentos, decidimos fazer o seguinte:
- Peça ao desenvolvedor para revisar documentos escritos.
- Se possível, atualize atempadamente a documentação, em primeiro lugar.
- Crie e adote um padrão para documentar projetos de NIB, para que todos possam entender rapidamente quais elementos do sistema e como descrevê-lo. Bem, desenvolva modelos apropriados.
Tudo isso deve ajudar a elevar a qualidade dos documentos a um novo nível.
Pelo menos espero que sim.