Good software documentation still seems a hurdle for even seasoned coders. Loads of software has very bad or just no documentation at all, even in the space of Commercial Off-The-Shelf (COTS) software products and enterprise-level custom development.
There are certain influences outside the coder’s control that obviously impact the problem. When budgets are tight, documentation is seen as non-functional payload and is often the first thing that gets scrapped from the planning. Also, many projects simply are not ‘rigged’ to cater for (good) documentation. Having certain methods and tools embedded in the project’s DNA goes a long way in getting coders to write documentation.
But the bigger problem seems to be that coders are trained to write code, not documentation. Back in the days (ancient in software development scope) we used to write pseudo-code before the actual code. Pseudo-code that looks a lot like usable code documentation. Pseudo-code has been surpassed (by the looks of it) by newer methodologies to design code, but we forgot the strongest feature of pseudo-code: you do it right there in the code, and when it stays there its great documentation. There is no other method that has this feature. However, for some strange reason, pseudo-code isn’t actively being taught in courses these days.
So where does this leave us. Let’s look at the possible scenarios…
The ugly: development -> delivery -> documentation (if any).
Yep, let’s start writing code right away. The client made it clear he needs it asap and we know what we’re doing, right? RIGHT? Well no, you can see a disaster coming from miles away. Without any engineering, which basically means you think about what you need to do and write that down for reference, today’s software complexity will roar its ugly head anytime soon in the project. Just hope it will be soon, or you will be left with an unmanageable mess of code without anything to help to make heads or tails from it.
But for the sake of argument, let’s say that this somehow gets us some working software, whatever that means without documentation. Now we can deliver to the client because the client doesn’t need documentation, he needs working software. We can do the documentation later, you know… if we even get to that. In most cases, the lack of documentation gets obvious much further in time, when the delivered system needs maintenance and the original coders find out that reading your own code after any reasonable period of time is pretty hard. That is, if the original coders are still available. If any coder, no matter how good and experienced, has to deal with undocumented code from another coder, he/she basically will have to do all the work all over again to figure out how the code should work.
The bad: development -> documentation -> delivery.
So we did the ‘let’s code right away’ and managed to survive that. But now we have a client that actually wants documentation as well, or any other prevalent reason that we MUST have documentation. No problem, we write it before delivery. Remember I said that code is hard to read, even for the original coder, after any reasonable period of time. So now the coder is basically doing all the thinking for the code AGAIN! This will take even more time then just writing the darn code. It might even shed light on ‘not so good’ code and trigger rewrites of large sections of code. By the way, why it is that ‘code refactoring’ (rewriting existing code) is seen as a solution (a method even) instead of a problem?
Documentation that is written after coding is almost always flawed. Because of bad memory, unreadable code, stuff that gets left out because it isn’t obvious, but in most cases a fatal combination of all those. Thinking about the code you wrote a week ago will never get you in the same mindset that you had when you actually wrote the code, even if only a week ago.
The good: documentation -> development -> delivery.
Writing documentation FIRST will help in writing good or even better code. It also helps a lot in client communications where the client has to sign off on things like requirements and such. Because documentation is not code (even if it is pseudo-code); it describes the inner workings of code in normal human-readable form. If written well, a non-coder should be able to understand it. If not, your documentation sucks, period.
Good up-front documentation makes coding light work… and very fast. Problems that can take days or even weeks to figure out in (already) written code, are easy to spot in well written pseud-code. Besides pseudo-code, stuff like short explanations of a function written up front leads to much better implementations because it leads the coder in thinking about what needs to be implemented.
Bottom line: good documentation, on every level, is not just another task in the project; it is one of the strongest tools you can have for delivering great code. Implementing a ‘write documentation first’ mentality can be trained by writing and using pseudo-code… just try it.
Related posts:
Software documentation: the good, the bad and the ugly. by HansPeterWillems.eu is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.