Why don’t we have more documentation?

I love this question. I’ve heard it a thousand times (well, maybe not a thousand, but pretty close). People ask this question with such consternation and condemnation in their eyes. They brow-beat you as if they just busted you for dodging the responsibility and due-diligence of documenting your work. Oh the superiority in their eyes is just priceless.

First off, let me say that I am very pro-documentation.  It is important and every company should have more documentation than they have.  However, they don’t.  It has taken me a while to get my head around this condition.

So, let me explain why every business is light on the documentation and why that is unlikely to change.

1. Priority
The company is paying developers to do what? They are paying us to do whatever they say. That could be: writing programs, designing web sites, mining data, writing reports, fixing a PC, installing software, (you get the picture). Heck, if they say we need to polish brass, we grab some Brasso and some cotton and start polishing. So, for starters, I’d say, look at my “to do” list and tell me where you want me to write docs and I’ll do it. It is that simple. However, the timeline doesn’t usually contain lots of time for docs.  Companies usually hire programmers to do programming. Documentation is usually a lower priority.

2. Cost
Documentation takes time and time is money. Therefore, every document costs money to write, but it doesn’t end there. If you have documentation, but don’t maintain it, how long will that documentation continue to retain its value? Not long. So, every doc that is produced is also a liability (to maintain). So, set aside even more time and money for retaining and maintaining it for a few years. Add that into the schedule.

3. Value
Cost is not really a problem though, because everything in business costs something. The real question is: does it bring value? How? If you spend money to make it and maintain docs, what is your ROI?
So, with a program, you can see your ROI every time someone uses the program and it saves them time or improves their accuracy or helps them stay organized. The ROI is obvious, which is why companies have programs written. However, when you apply this logic to docs, what do you see? The docs should save their users some time and improve their accuracy and help them stay organized. Okay, that seems reasonable.

Who are the users of the docs and how do the docs provide value to them?

  • Upper Management/Operations – Use documentation to define processes for a business so they can be analyzed, optimized, split/merged or taught to new employees. These people do not want to drown in details. Their time is money and docs need to save them time. That is the bottom-line.  They want summaries and 1000 ft views.
  • Project Management – The PMs need to keep track of what needs to be done. They need to be assured that the developers have well-thought-out plans and are sticking to the plans. They need to be assured that the program that is being written is what the end-users actually want. The docs are, to some degree, simply legalese. The PM simply needs to make sure the docs exist and are adequate and measurable.
  • BA, testers & developers – The documentation is the to-do list. It contains details. Any detail that is not contained in the docs, is a license for a developer to get creative (not necessarily a bad thing). Once a project is done, the docs are simply a historical account of what transpired.
  • Users, Subject-matter-experts – The documentation is a translation of the business need into something that the developers will use. Docs are a large risk to this group because it documents what was requested and if it is garbage, it is very condemning. It is also extraordinarily tedious and long-winded, filled with abstractions within abstractions intermingled with enigmas and legalese. It is a box full of deadly vipers that need to be fed and nurtured.  Users and SMEs want to change that dirty diaper and get back to hugging their baby (metaphorically speaking).
  • Support team – The documentation will describe how the system works. There will be idiosyncrasies and security rules and everything that an end-user will ask about because they are baffled. If there are error messages, those will be explained in the docs too. Basically, the docs will contain everything that nobody thought of.  Anything else is going to slow them down and hinder their jobs.
  • IT infrastructure – This team needs to install the program and if something breaks, they need to know what to do to fix it so the phone stops ringing and they can get back to the stuff that they were actually scheduled to do today. This team wants information that nobody else wants to see and nothing more.

So, considering each of these people and their uses for the documentation, how much overlap did you identify? Maybe 5 to 15%? The docs for any one of these teams will not offer much value to another team. In fact, they will likely interfere with the productivity of the other teams as they wade through the docs for the information that they actually need. Some of the docs are only useful before the program launches and some are only useful after the program launches.

This list really points out the conflict and complexity of producing documentation with any lasting value. The term “documentation” almost takes-on two or three completely different meanings, depending on who you are asking.

As a metaphor, think of writing a program that is designed with six screens/views for each feature or maybe a report with the same data displayed six different ways. The cost/time goes way up with each distinct user group. Management is going to waffle at the price tag. So, you will consider cutting the scope (which ultimately translates into writing less docs, or docs that are less detailed/meaningful, so they are generic enough to meet the needs of several groups).


Here is the real ROI matter: You need to have an understanding of the needs of each of these groups so your docs will meet their needs. Otherwise, your documentation doesn’t add value. It may actually subtract value.  When you consider the risk of producing docs that result in negative ROI, things get pretty serious.  This highlights the root of the reason many companies avoid documentation.

One reasonable alternative is to have each of these groups write their own documentation. To do that, these groups will need to have an understanding of what documentation structure/format will provide value to their group. Then, they need to gather their own information and document it. Then, they need to maintain their own docs. So now, instead of one group gathering requirements, you have six and each has a different agenda and a different level of detail/complexity that they are pursuing.

In the end, the IT groups are the ones who will see the greatest value out of these docs. With the BA/Test/Dev group, the relationship with the docs is bittersweet. This is because the BA/Dev team will spend their time writing docs that are only useful during the project lifecycle. The docs are essentially, another set of code that needs to be scoped, written, tested and debugged. After the project is completed, the program will be launched and the docs will be moth-balled.  Let me say that again: for BAs/Testers/Developers, the documentation only provides a value during the project.  After the project, it has no further use.  So, you spend much time building something that has a very short life-expectancy.

Next, I will talk about where/when you get the most ROI from docs.  Continue to part 2.


About Tim Golisch

I'm a geek. I do geeky things.
This entry was posted in IT Psychology, Methodology. Bookmark the permalink.

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