Agile development experiences - Part 2: Working software over comprehensive documentation

In the last post about the first agile value, Individuals and interactions over processes and tools, I talked about my experiences how to use this to introduce effective teams. Now I want to dive into the second value, Working software over comprehensive documentation. You'll see that I write a lot about documentation, because it is the widely ignored but still important part of this agile value.

TL;DR

• Write at least a short architecture documentation, e. g. with the arc42 template. This helps to understand the basics of the software.
• Document important decisions at least in some compressed format, e. g. as Architecture Decision Record.
• Check if there is something required by company rules or law. You just need to write this kind of documentation.
• Use Docs-as-Code to utilize tools you are used to as a developer. This will make writing documentation a lot easier and less painful.
• Make documentation part of your daily workflow. You will get used to it and improve your software a lot.
• Document your code, even if "Clean Code" is popular and tells you different. A well documented codebase is far more maintainable than hundreds of small methods with long camel case names.
• Define what "working" software is in your context and find an iteration length that supports the achievement of this definition

"Working software over comprehensive documentation"

This value is, in my opinion, the most misunderstood or misinterpreted one. Many people I met interpreted it as "You don't need documentation, the code is your documentation", often supported by Robert C. Martin's book "Clean code". Anyway, it seems that those people didn't read the value and the manifesto exactly, since it says you don't need comprehensive documentation. My interpretation is this: "You should focus on working software and document everything necessary to understand why the product exists, how it is designed and what it is able to do". This way you can decide where more or less documentation is required and how / where it is written. Let's start with my experiences in writing compact but helpful documentation.

Use modular templates for your documentation

In the past documentation was often a big bunch of documents that were never updated anymore after their creation. The value was nearly zero and nobody wants to work with them. In many cases I saw that those documents either had no structure or tried to use some static enterprise template that requires a lot of work to fill and keep it up to date.

To avoid this, I started to use modular document templates like arc42. These templates provide a clear structure but don't require you to fill out everything. Also they can be used even in legacy systems to getting started with documentation.

Make documentation part of your workflow

In the past writing documentation was sometimes delegated to other people than the developers implementing the software. This fact led to knowledge gaps and boring hours of writing a lot of text. Sure, this is everything but motivating. But how can you do this better?

To avoid this situation, I prefer to include the documentation work as acceptance criteria in my tickets, so I have to document only small parts and it cannot be forgotten. Also everyone is required to write something which can lead to constructive discussions and writing documentation gets a habit. In the beginning it is hard, but after some time you get used to it.

Use Docs-as-Code if you are allowed to

Be honest, who likes Word or weird Wikis? Probably business people. But when you are reading this you are likely a developer or some tech person. So you are used to code and why shouldn't you use code to write your documentation? AsciiDoc or Markdown are great tools for this and can be included into build pipelines etc.

Document only necessary things

Maybe the hardest thing to determine is, what things are necessary to document. Now, the most important things are regulatoric topics that just MUST be documented to avoid fines. The other things that should be at least documented are how to start the development environment, how to deploy the application and probably some architectural information to get a brief overview.

Inside the code you should document at least the public APIs, event if you wrote the best and cleanest code that would make Uncle Bob proud of you. You ask why? It is really easy: you don't want to know HOW and API works, but you want to know WHAT it does and probably WHY. And this WHAT and WHY are things that should not change in a public API, so the documentation shouldn't change often too. Imagine the JDK had no documentation. Would you use it? Would you want to dig into highly optimized, probably cryptical code where the documentation just explains something conceptually simple like this?

    /**
     * Increases the capacity of this {@code ArrayList} instance, if
     * necessary, to ensure that it can hold at least the number of elements
     * specified by the minimum capacity argument.
     *
     * @param minCapacity the desired minimum capacity
     */

Personally, I don't want to do this, so I favor a short and descriptive documentation for public APIs instead of so called "self-explaining code". Understandable and working code is great, but understandable working code AND good documentation together are perfect.

What about the "working software" part?

To be honest I think this is a highly complex topic, since the definition of "working" is completely dependent on the project itself. "Working software" for a inhouse software that is used once in a year by two pleople has another definition than for medical or military equipment. So the only recommendation here is to say: define what "working" means in your environment and try to find a way to create software satisfying this definition in your iteration's bounds.

Note: I've no idea how often I wrote something for this topic and deleted it again. So in case you want to discuss "Working software" please feel free to contact me.

Relevant principles and conclusion

As in the post before I want to share the agile principles which I think are helpful as guidelines for this agile value:

Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.

Deliver working software frequently, from a couple of weeks to a couple of months, with a preference to the shorter timescale.

Working software is the primary measure of progress.

Continuous attention to technical excellence and good design enhances agility.

Agile Manifesto

In the next blog I'll talk about Customer collaboration over contract negotiation, whereas I must say that I can't say anything about contract negotiation because that was never part of my work.