Virtually everyone complains that there is poor Documentation for software systems. However, if you ask the same people during a project to document what they are doing then they will tell you that they are too busy and that they will document things later.  The reality is that the documentation rarely gets done, and when it does, it is often useless or too high level.

What is going on here?

This is like when Alice in Wonderland visits the White Queen who offers her jam tomorrow.  But of course, tomorrow never comes.  So when someone says that the documentation will be done later, they are telling you that the documentation will never be done.

Claims that documentation will eventually be done are lies

So the first point to clarify is that just because documentation is done does not mean that documentation exists. For the purposes of this article, the documentation exists if:

The documentation actually helps to understand the program

Let’s motivate the discussion of why documentation is often poor or missing with a common situation. Let start with low level code comments, quite often you run across such code comments:

// Convert float to string
$value = float_to_string( $value );

This is not documentation.  This kind of comment can often be found in code for organizations that insist that a certain number of comments be created.  This comment is worse than useless because it takes up space for no reason whatsoever.  For other reasons why code comments are problematic see Comments are for Losers.

Code comments should not tell us why the code is doing something but rather why the code is doing it.  If other developers can’t read your code and understand what it is doing then that is a different problem.

Similarly at a high level, documentation should explain why something is being done, not how it is being done.  For example, writing down directions to get to a friend’s house does not explain why you are going to your friends house.  Yet most of the documentation that we produce resembles this, it is a documentation of the obvious.

Good documentation focuses on what is being done, not how it is being done

The interesting thing is that developers are fairly disciplined about using version control systems, yet there is a complete lack of discipline (in general) when it comes to documentation.

Of course I expect documentation to be done if the project is poorly planned and there is not enough time to even implement the code.  Projects that are doomed to failure before they start have much bigger problems than documentation to solve.  Projects that are properly planned but are executed with organizations with common bad practices will also likely have a failed project (see Stop It! No… really stop it).

So it stands to reason that only the 30% of successful projects out there should be concerned about documentation.  The other 70% have many other issues to figure out first, like for example, how to execute a successful project (see Failed? You get what you deserve!).

If you don’t have repeatable and reliable processes for successful projects, then documentation is not your biggest problem

One of the reasons that documentation is so poor is that we tend to write it after we have gotten the code working.  Once the code is working, our minds are focused on what it did to get the code working and we then document what we consider to be the difficult part of the implementation.

The only time that you are thinking about what you are trying to do is before you have written the code.  This is clearly the best time to write the documentation.  The problem is that developers move from thinking about how to solve a problem to getting their hands on the keyboard to write code to solve the problem.  In the blink of an eye the programmer switches modes and gets caught up in trying to solve the problem.

So if you seriously want your projects to be documented, then you must document the ‘what’ before your hands hit the keyboard and you are caught up in solving the problem.

Also, documentation is something that needs to be done every day. Waiting until the end of the project and assuming that you will remember what you were thinking about how to achieve the various project goals is virtually impossible.

Good documentation requires just as much (if not more) thinking than what is required to solve the problem.  Much of the time people don’t have a good idea of what problem they are solving.  By truly spending time on figuring out what you have to solve, then documenting it, sounds like it would take longer — but you will be surprised to find out that this actually saves time.

Note, if you don’t produce good documentation then you shouldn’t expect anyone else to either.

Note, this is not associative, i.e. just because you produce good documentation will not entitle you to expect that anyone else does