Is there any good documentation?

Its normal for many to say, “If you do agile there is no documentation“, but is that really true? If we go to the manifesto, it says “Working software over comprehensive documentation”, over is not instead. It is also reinforced by “while there is value in the items on the right, we value the items on the left more”. So is there any value on documentation?

Spoiler alert, YES. Not all documentation is created equal, and not all documentation is bad. There I said it…

In the last post I’ve touched on two types of documents. Those two in my opinion are utterly useless. They serve no purpose except to waste time and money from an organization. If you want to read more about them click here.

So what is good documentation?

First let’s stop, regroup and relax for a bit.
Bread in.. Bread out…
Just because there is good documentation, that doesn’t mean that you should go and spend the next 8h on it.
The one thing that makes documentation good, is that it needs to be concise and short. Right to the point. If there is more text that needed to convey the main idea, you are going in the wrong direction.

When you are developing software, the value you produce is in the software itself. All documentation that you’ve produced before, to explain what you are going to do is trash the moment the project it’s done.

A good piece of software is like a good joke. If you have to explain it, you are doing it wrong.

So what is good documentation? Well, it comes in many forms.
It could be a Pull Request when code goes to the main branch.
It can be a diagram explaining how systems will integrate together (nothing fancy, a pic of a white-board or sketch on paper).
It can be in the code itself. There are many more, but one thing they all have in common is that they don’t require a sign off.

Let’s start drilling down on the different types of documentation.

Functional Documentation

User Stories & Backlog Items

The easiest and most useful ways to create functional documentation “The user Story”.

A user story is able to convey a lot of information “As <<someone>> I want to do <<something>> so that <<outcome>>”. With this syntax is very easy to understand who is your customer, what it wants to do and why he wants to do that. We can also add an acceptance criteria and make it easier for the team to develop and test this feature.

So I ask you now. Do we really need a big document? Those that most of it is copy pasted from previous projects. Or can we get away with a simple sentence to convey what we want?

That doesn’t mean that all backlog items need to be user stories. You can have other types that go from Tasks to Spikes to whatever. The one thing they all have in common is a simple syntax and no useless text.

Drawings & Sketches

For me, this is the one. This is the most important and useful type of functional documentation that exists.

Photo by Startup Stock Photos on

They say that a picture is worth a thousand words. For me, drawing on a white-board is worth a thousand paragraphs. There is so much information that we can share with lines and boxes, that would be lost if was written in text.

You can even provide a lot of details with a drawing, or keep it simple and provide an overview.
In my opinion, drawings with lots of details fall into the same pitfalls as extensive documentation. They become so full of information that one starts to wonder… Is this a “Where is Waldo” drawing? It’s hard to find what you are looking for…

Technical Documentation

“Truth can only be found in one place: the code.”

Robert C. Martin ( Uncle Bob )

Code comments

In my days as a developers, one of the first things I’ve tried with all my teams was to come to some kind of “code standard”. This agreement is very important. Why? Because it prevents the need of extra comments or documentation to explain the code. If everyone understands and speaks the same language, communication is fluid.

Each developer has different ways to code, and that’s OK. With a bit of alignment, communication is easier. Pull requests get approved and validated faster. Anyone will be able to pick up your code and improve it/debug it. The code becomes smaller because you don’t need many comments on it.

But nevertheless, there is always some comments that may be needed.

A good rule of thumb is, if you have as much or more comments than code, you are doing something really wrong. Comments are supposed to aid when you are reading the code. They bring that little bit of extra light on a function or statement. They serve no purpose if they are explaining what exactly is happening.

Comments are not an excuse to replace good clean code. But in the right amount, they have their value.

Comments are very useful when you go back to correct a bug. If you comment were the correction took place, for example, with the number of your ticketing software of choice, anyone will be able to track it for eternity.

Pull Requests

As technical documentation goes, this is probably the best summary you can find.

I had a team before were we use to provide a good technical explanation on every PR. Sometimes even with print screens of the application and tests that were executed. This helps creates a snapshot of that moment in time that never needs to be updated.

When you are creating something new, this is where you share with your peers what you did and how it works. PR in this way are like a living organism. If the info you provided is not enough, your peer will comment and ask for more. If the information is not clear, they will ask for clarification. The PR will evolve until it is completely clear.

Please note that when I say completely clear, it is clear for the people that work on it. It is not clear language for managers to read or committees to approve. A PR is useful documentation because it knows its audience and the speech is aligned to that audience.

Wrapping up

There is good functional and technical documentation in this world. They have a clear purpose. Aligned to the target audience. They are small and simple.
When a manager or an executive do CAPEX or TCO analysis, they don’t write for developers can understand. And that’s OK, they are not the target audience.
When developers write documentation, they need to write it in a way that is useful for them.

In a very quick summary, don´t write more than you need and know your audience. If you are copy pasting something, you are doing it wrong.

Do you have other types of what can be considered good documentation?
If so please leave a comment or reach out, I know I’ve missed some but would love to hear your thoughts on it.



Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

search previous next tag category expand menu location phone mail time cart zoom edit close