Documentation is a very special topics to talk about. I discovered, I have to write more than one blog to cover this topis at least a bit. so lets start:
Just to remember – in 2001 a group of agile individuals phrased the agile manifesto and the twelve principles of agile software that are relevant as ever. With respect of this blog discussion about documentation in our agile & lean world I would like to repeat the interesting statements.
- Working software over comprehensive documentation
Twelve Principles of Agile Software
- Welcome changing requirements, even late in development. Agile processes harness change for the customer's competitive advantage.
- Business people and developers must work together daily throughout the project.
- The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.
- Agile processes promote sustainable development. The sponsors, developers, and users should be able to maintain a constant pace indefinitely.
- Simplicity--the art of maximizing the amount of work not done--is essential.
Just to point out: The other statements are as relevant. This subset is chosen in respect of the discussion in this blog.
In an agile & lean organization a core attribute is the continuous flow of development and improvement. An important impact is that many things are “in progress” at different level of maturity. As well many things are “done” and in operative use, like a deployed feature in our online-shop or erp-system.
This is where documentation comes into place. Core questions are: Who needs a documentation? What is the benefit of a documentation? To answer these questions, I present some typical scenarios out of our company
Scenario 1: The checkout process requires a change because of a new feature
Imagine we want to add a new feature like a new delivery option in our online-shop checkout process. The checkout process is a complex business process with many scenarios, dependencies, decisions and business rules behind. The working software unluckily is not a sufficient information source to change this complex process. To remind ourselves on all the decisions, business rules and compliance regulations is important before we change this process. As business people from all departments have stakes in this process (accounting, logistics, product management) source code is for sure the only truth of what is implemented, but for sure not best suited for the business people. So there is a need for some form of documentation beside the source code. Let’s phrase his need as a user story: “As a business reader I want to remind myself based on an easy to search, read and understand documentation what we decided that last time we worked on the checkout process.” Additional, as soon as the new checkout process is implemented the delivery process is changed as well leading to changes in operational process in logistics. This requires that we rollout the operational changes and educate our staff members in logistics how to deal with the new process. Therefore, we need some documentation as well.
Scenario 2: We want to rewrite the ranking algorithm of our products
Imagine we discovered that the ranking of products in our online-shop does not meet the expectations of you as a user searching for products. Ranking of products is a complicated (not a complex) algorithm. Many influencing factors determine the rank of a product. You might imagine some of them like: number of visits, numbers of sales in total, number of sales during a certain period, number of recommendations of customers who bought an article of this product…and some more factors. All these factor go into an algorithm. You can imagine that this algorithm is as complicated and secret as the ranking algorithm of Google in their search engine. In fact is kind of a similar problem. To nail this algorithm done more than one session with the right person on board (head marketing, head engineering, product managers, software engineers, …) is necessary. The outcome of these meetings in the end is kind of a decision table that lists the factors and the weight and influence of each factor in the algorithm. An excel table would fit – but unluckily you cannot discuss on base of an Excel table with a product manager for toys or living accessoires. To summarize: The user story to implement might be easy: As a user I want the products in the online-shop ranked in a way so that I find interesting offerings fast and at top on first view. The requiremrent engineering process to elicitate and specify the algorithm needs documentation in some form – as preparation, as discussion base, as outcome for implementation and test (algorithm, acceptance criteria, test data, …). And at the time this new algorithm is implemented maybe we want to change it in six months again. Then scenario 1 comes into play.
I hope these two scenarios give you an insight why even in agile development documentation beside the source code is required in some form. Still we all are convinced that the best documentation is the one never written and we try to share information as far as possible by direct face to face communication. We encountered that this is unluckily not sufficient. So we strive to create just that minimum amount of documentation for readers and target groups that is sufficient to follow a sustainable path of development and improvement in our documentation.
Let’s see in some additional blogs what our idea about an agile documentation is – at least what we hope will meet our needs and deliver benefit. We are still on the road to establish a good agile documentation; we already found some good techniques and tools, but we still have lots of room for improvement.