Documentação Ágil

Muito tem se falado de motodologias ágeis, principalmente no meu ambiente de trabalho, onde aplicamos a metodologia Scrum.

Muita coisa mudou ano passado com o novo andar da carruagem. Porém, um problema ainda persiste…. e a documentação? Onde fica? Não fica?

E quem foi que disse que as metodologias ágeis são contra documentações?

Andei lendo alguns blogs, entre eles o do Vinicuis Teles, da ImproveIt, Vinicus Lourenço, The Developers Conference e Agile Modeling para me atualizar e ver a opinião de outras pessoas. No GUJ também temos essa discussão sobre o mesmo assunto!

Conversando com um amigo de uma amiga minha que mora em Portugal, acompanhados de salgadinhos deliciosos do Boteco Belmonte no Leblon, vimos que esse é um problema comum entre as empresas que adotaram metodologias ágeis. Esqueceram da documentação por acharem que deve-se produzir (e muito) sem precisar documentar!

O problema é que estamos acostumados com o modelo Waterfall, no qual esperamos que todos os requisitos venham super bem detalhados para que a documentação possa ser produzida e somente após o design da aplicação ser feito, o desenvolvimento era iniciado. Quem nunca precisou alterar um requerimento que impactaria diretamente na documentação e no final das contas, o software não (quase nunca) refletia o que havia sido solicitado inicialmente? Jogue a primeira pedra quem nunca passou por isso!

Bem, então vieram as metodologias ágeis que vieram pra derrubar o modelo Waterfall para que software começasse a ser produzido com um mínimo de requisitos e com uma proximidade maior do cliente para que o software pudesse evoluir corretamente. Os requisitos vão sendo obtidos ao longo do sprint para ajustes e não para grandes mudanças. O entendimento quase total, deve ser feito nos plannings. Na minha opinião, o erro está exatamente nesse ponto!

Se estamos planejando o próximo sprint, porque não incluir o ítem documentação como tarefa de desenvolvimento? E como fazer isso de forma mais ágil? Que nível de documentação precisamos fazer? Como disponibilizar toda essa documentação para que fique algo inteligível? E os sistemas legados? Mas pra que documentar?

Recomendo e muito a leitura do site Agile Modeling, na parte onde se fala de documentação.

Pra mim, a leitura de dois principais pontos, refletem e dão dicas dos principais problemas sobre documentação ágil. São eles:

---

Critical Points

1. The fundamental issue is communication, not documentation.
2. Agilists write documentation if that’s the best way to achieve the relevant goals, but there often proves to be better ways to achieve those goals than writing static documentation.
3. Document stable things, not speculative things.
4. Take an evolutionary approach to documentation development, seeking and then acting on feedback on a regular basis.
5. Prefer executable work products such as customer tests and developer tests over static work products such as plain old documentation (POD).
6. You should understand the total cost of ownership (TCO) for a document, and someone must explicitly choose to make that investment.
7. Well-written documentation supports organizational memory effectively, but is a poor way to communicate during a project.
8. Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.
9. With high quality source code and a test suite to back it up you need a lot less system documentation.
10. Travel as light as you possibly can.
11. Documentation should be just barely good enough.
12. Comprehensive documentation does not ensure project success, in fact, it increases your chance of failure.
13. Models are not necessarily documents, and documents are not necessarily models.
14. Documentation is as much a part of the system as the source code.
15. Your team’s primary goal is to develop software, its secondary goal is to enable your next effort.
16. The benefit of having documentation must be greater than the cost of creating and maintaining it.
17. Developers rarely trust the documentation, particularly detailed documentation because it’s usually out of sync with the code.
18. Each system has its own unique documentation needs, one size does not fit all.
19. Ask whether you NEED the documentation, not whether you want it.
20. The investment in system documentation is a business decision, not a technical one.
21. Create documentation only when you need it at the appropriate point in the lifecycle.
22. Update documentation only when it hurts.

---

Why Do People Document?
Agile developers recognize that documentation is an intrinsic part of any system, the creation and maintenance of which is a “necessary evil” to some and an enjoyable task for others, an aspect of software development that can be made agile when you choose to do so.  There are several valid reasons to create documentation:

1. Your project stakeholders require it.  The creation of documentation is fundamentally a business decision, you are investing the resources of your project stakeholders in the development of the documentation therefore they should have the final say on whether their money is to be spent that way, not a technical one.  If your project stakeholders request a document from you, perhaps at your suggestion, and understand the trade-offs involved (more on this later), then you must create the document.  It is important to note that eXtreme Programming (XP) is very explicit about documentation being a business decision.  You should create documentation only when your project stakeholders ask you to?  Preposterous you say!  Well, my experience is that this isn’t preposterous. Your project stakeholders include a wide variety of people, including all of the clients of your system, and therefore they should have a reasonably good idea what they want.  Maintenance developers, or someone representing them if they are not in place yet, will request system overview documentation.  Users and their management will likely request user documentation.  Operations staff will request operations documentation.  Yes, you will need to work closely with them to determine what they actually need, someone is going to have to decide to pay for the development and subsequent maintenance of the documentation, and you may even need to explain the implications of what is being requested, but this is doable.
2. To define a contract model.  Contract models define how your system and an external one interacts with one another, some interactions are bi-directional whereas others are uni-directional, making the interaction(s) explicitly to everyone involved.  Contract models are often required when an external group controls an information resource that your system requires, such as a database, legacy application or information service. The AM practice Formalize Contract Models states that a contract model is something that both parties should mutually agree to, document, and change over time if required.  It is important to understand that the development of a contract model should still be verified by your project stakeholders – it is their money that you are spending, and if they choose to go at risk and not have the contract model in place then that is their choice.
3. To support communication with an external group.  It isn’t always possible to co-locate a development team and it isn’t always possible to have project stakeholders (or at least the ones you need at the time) available at all times.  When you need to work with an external group of people you need to find ways to communicate with them, and shared documentation is often part of the solution in combination with occasional face-to-face discussions, teleconferencing, email, and collaborative tools.  It is a mistake to use documentation as your primary means of communication because it’s far too easy to misunderstand something that has been written, but it is a good supporting mechanism.  A good way to think of documentation in this situation is that it is your option of last resort.  Note that this in effect is an extension of the practice Model to Communicate into the realm of documentation.
4. To support organizational memory.  One of the principles of Agile Modeling is Enabling the Next Effort is Your Secondary Goal which is meant as a counter-balance to the principle Working Software is Your Primary Goal.   An important implication is that we not only need to develop software, but we also need to develop the supporting documentation required to use, operate, support, and maintain the software over time.
5. For audit purposes. I’ve worked in organizations where we’ve developed life-critical systems, and those systems fell under the auspices of the US Food and Drug Administration (FDA) audit guidelines.  I’ve also worked in organizations where Sarbanes-Oxley (SOX or Sarbox) and/or BASEL-II were applicable.  The common theme was that we had to follow a defined process and capture proof that we did so, resulting in more documentation than we would have normally written.  In these situations you still want to create just enough documentation to get the job done.  A common mistake that I see get made is that the bureaucrats jump on the “We’re might get audited by so-and-so, therefore we need to produce the following documentation…”.  My advice is to read the appropriate guidelines yourself, because they rarely require what the bureaucrats think they require.  Be smart about compliance.
6. To think something through.  Many people will write documentation to either to verify for themselves some group work they had just been involved with or simply to increase their own understanding.  The act of writing, of putting your ideas down on paper, can help you to solidify them and discover problems with your thinking.  What appears clear and straightforward in your mind can often prove to be very complicated once you attempt to describe it in detail, and you can often benefit from writing it down first.  It is for this reason that I suggest that people write comments before they write their code, a practice that I have been following for years.

---

Acho que a maioria das respostas encontram-se nos 6 itens acima!

O nível de detalhamento da documentação, depende e muito do que está se produzindo.

Bem, ainda não tenho resposta pra tudo, infelizmente! Acho que da mesma forma que temos que entregar novos sistemas com testes automatizados e com uma boa cobertura, documentos de aceitação, etc, precisamos também entregar o sistema com alguma documentação (ou não!).

É uma questão a ser discutida entre o time e o PO para que se chegue numa documentação que esteja de acordo com o que ele precisa e que ele tenha noção que o benefício de se ter documentação deve ser maior que o custo de criação e manutenção do mesmo! “16. The benefit of having documentation must be greater than the cost of creating and maintaining it.”

De nada adianta produzir documentação e não manter ela atualizada, como acontece na maioria dos projetos!

No caso dos projetos que participo, é que temos MUITA regra de negócio e elas são super complexas! Temos que chegar num ponto ideal onde a documentação solidifique o conhecimento de todas as regras de negócio sem chegar muito na parte técnica do sistema. A documentação deve servir para que o PO possa ler e entender sem precisar sempre requisitar alguém do time para explicar como A, B e C funcionam no contexto X, Y e Z!

Ainda nem começamos a documentar pra falar a verdade! Passamos 1 ano desenvolvendo e não criamos 1 linha de documentação! Logo, ainda estamos pensando na melhor forma de se produzir esses artefator sem honerar demais o Sprint!

Bem, evoluindo um pouco no assunto…

Acho que uma boa forma de se “entregar” uma documentação de forma ágil, seria usando BDD. Li um post do Alexandre Martins sobre o JBehave que muito me interessou! Indico também a leitura desse artigo.

Acho que podemos entregar uma documentação interativa, onde escreve-se cenários e os mesmos são integrados com o sistema, como se fossem testes JUnits!

Vamos estudar outras ferramentas que facilitem a geração de documentação ágil! Agradeceria dicas e comentários a respeito!

Ao longo do ano de 2009 começaremos a discutir com mais afinco esse problema no noso time! E deixarei aqui os registros dessa “evolução”! 🙂

Aproveito pra desejar um excelente 2009 pra todos!