Why extensive documentation is useless and creates legacy

I have always been a proponent of documenting only if necessary. The less you write, the easier is to keep updated.
No one likes to read a 50 page document. A good book, maybe …

If you think the main goal of extensive documentation is to help developers, let me break it to you, they wont read it. Unless you force them to.
If you want to improve their communication, buy a whiteboard.
When they need to discuss something technical, they will go in front of it and start sketching. That’s were the value is.

Extensive documentation creates outdated software, before starting development.

TD’s and FD’s are useless, but that doesn’t mean all documentation is useless.
Some is useful, some is useless.
In this article I will focus only on the useless ones I’ve experienced so dar.
I will focus first on these because I think that if you can reduce the time you waste on them, you will become more productive.


Functional Designs Documents

This gives me a chill down my spine. Ohhh how I remember … The days of writing functional design documents.
Have them approved by committee of managers that knew very little about what was going to happen.
Don’t hate the managers for that. Let me be clear here, that is how it should be, a manager shouldn’t be worried FD documents. There are more important uses of their time.

You create this document to safeguard yourself from customer changes (what if change is good ?). This document will become the “agreement” between you both when the sign off is finished.
So what is the big problem in this ?
Sounds good to have an agreement. Why is this so bad ?

Well … This document exists to create another document.

Isn’t that crazy just by itself ? It’s like planning a meeting to plan another meeting … How wasteful is this ?

Another problem is, if you try to specify everything before you start doing it, lets just say that the world is unpredictable.
☝️ Market changes.
✌️ Requirement changes.
👊*KAPOU* Without you noticing, your customer changes.
Locking something in a moment in time, even if functional, is creating legacy.
There is a very high change the functionality will need to be changed.

There is one even worst …
What if longer make sense to do it?
What will you do then ?
It is written down. Signed off. Budgeted. Time was already wasted thinking about it. What will you do ?

This is the main reason why I don’t believe that FD’s bring any value to the table.

If you want to discuss functionalities, there are a lot of better ways of doing that.
What is your main goal ?
Building something good for your client or bleed them out in change requests ?


Technical Design Documents

OK, now you checked all the functional boxes out, is time to lock everything at a technical level.

I believe in technical documentation. No I am not kidding, I believe that good technical documentation helps everyone in the future. What I don’t believe is the kind that comes wrapped in a technical design document, ready to be signed off.

A technical documentation can be an image on a whiteboard.

Photo by Kaleidico on Unsplash

Code comments. Pull request discussion. Commit messages.
All of this is exponentially more value than 100 pages of a technical design document.
OK maybe I am bickering too much at technical design documents. Maybe they have some value for the team … 👇

A technical design documents can be as good for the team, as the asteroid impact was good for the dinosaurs.

The problem is again the same as before. These documents are created for a sign off. Remember, the goal is not to help development, the goal is to get a sign off.


And after all this ordeal of endless documentation and sign off is over, you can start the valuable work.
Does this make sense to you ?
Oh, and by the way, what you are going to build cannot deviate from the original documents. If it does, we need to activate the change management process.

Don’t fall victim of this pitfalls.

Be a friend, save a buddy, kill that document.


Cheers,



Join this newsletter to get exclusive content.

One thought on “Why extensive documentation is useless and creates legacy”

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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