Blogi 9.11.2017

Documentation Chaos is Avoidable in Software Projects – Part 1

Kiva kun löysit tämän artikkelin! Se sisältää varmasti hyvää tietoa, mutta pidäthän mielessä, että se on kirjoitettu 7 vuotta sitten.

fighting document chaos
Raise a hand those of you whose software project’s documentation needs updating? If you are working on a normal software project, you probably raised your hand. Typically, project documentation is outdated, contains useless information, and is scattered around. This blog post reveals the reasons for this ‘documentation chaos’ and how you can prevent it.

Reasons for The Chaos

Before we jump into the details, it’s good to understand what `documentation` means. Documentation is the information that describes the product to its users. This blog post focuses only on maintained documentation so, user stories, whiteboard drawings, PowerPoint presentations and UX-sketches are ignored.
The next question is, why software projects are facing documentation chaos? One reason is that, while only programmers see the code, documentation is visible to everybody. Therefore, documentation can be seen as a symbol of the quality of the software. Some projects` boundary conditions also require high documentation standards.
Another reason is the project lifecycle. The development team gather and document random information when a new project starts. When the deadlines are coming and budgets are running out, the team concentrates on developing software and fixing bugs and stop maintaining the documentation. In my experience, this is a very typical situation in software projects.
Universities have a very theoretical approach to software development. Courses are full of rules and regulations about how you should write documentation. In addition, courses, for example, determine at a very detailed level what documentation is needed in different phases and reference groups. This approach gives a misguided picture to students and reflects on the whole software development community.
Sometimes documentation chaos is caused by the software project structure. If the project has only a few skilled developers but many consultants and managers, documentation becomes an absolute value. The result is a massive set of documentation without working software. While documentation is visible to all, documentation costs are not.

But it’s just a piece of paper?

When the amount of documentation exceeds a certain level, documentation turns against itself. This is because documentation is valid only when it’s up to date. Documentation costs are easy to understand through this example.
Let’s have a project which needs only 200 pages of documentation in total. According to these sources (link1, link2, link3), it takes 2 – 4 hours to write a text page. We are fast writers so writing 200 pages of documentation takes us 400 hours. It’s only 53 man-days and is easily defensible.
Let’s decide that the project’s lifespan is two years. According to the same sources, it takes 1 hour on average, to revise a text page. If documentation needs to be changed on average once a month, it takes a total of 200 man-days. This time, it is more but still manageable.
Let’s have a second project which needs 2000 pages of documentation. Usually, this means that the product’s business rules are part of the documentation. On this occasion, the numbers are 530 and 2000 man-days. It’s more than 2 years non-stop work, for a team of five.

Less Documentation, Less Worries

‘If I had asked people what they wanted, they would have said faster horses’ is a famous quote by Henry Ford. Product owners and other decision makers want the top product which is fully documented. Unfortunately, documentation is expensive as the previous example showed.
The best way to prevent documentation chaos is to focus on quality over quantity. It’s better to have one page up to date than ten pages outdated. Here are some practical tips to keep documentation chaos under control:

Make documentation costs visible. New documentation is a new user story and will be will be prioritised against other stories
Don’t create documentation without the team commitment that documentation must be kept up to date
Keep documentation close to the source code. Comments, dynamic guides and scripts beat Word documents and wiki-pages
Document every business rule and screens only if someone `holds a gun to your head’
Most of the formal UML-models are too heavyweight for today’s software development
The more detailed the documentation, the greater the amount, and the bigger the risk that documentation is outdated
Create a culture where most design, such as sketches, drawings, and prototypes, will be disposable
Use images and avoid long text. Humankind has painted caves ten times longer than it has written texts

Self-caused, Self-fixed

Integration problems, complicated customers, and wrong technologies. Many typical problems are, at least partly, coming from outside. In contrast, documentation chaos is self-caused and self-perpetuated. The positive side is that the project team has the power to stop the chaos.
My next blog post will share more concrete examples of how to improve documentation and what is my ‘Minimum Viable Documentation’.