by Geoffrey Slinker
| Accesses: |
| Maverick Development |
version 1.5 Draft (March 2006)
The reason of documentation must be understood. Given a reason or a goal of a task then the task can be replaced or improved. Documentation for the sake of documentation is not reason enough for the effort.
Simply answered, "Because software solutions are complex and unforgiving and humans are quick to forget"
What is the purpose of documentation? To communicate. If accurate communication does not occur then the document was useless to the reader or audience.
This is a question that results in so many answers one is sure to fail to come up with all of the reasons. But this doesn't mean we shouldn't try to discover an essence or fundamental guiding reasons for documenting code.
One could ask when this requirement of documenting code came into practice. Discovering when might lead to information that would reveal the reasons why. This historical context is something that would be interesting to hear but is not necessary to discover the current reasons why there is software documentation.
Software documentation is defined to be "The organized collection of records that describe the structure, purpose, operation, maintenance, and data requirements for a computer program, operating system, or hardware device."
Documentation can also be used to capture thoughts, feelings, reasons, and any other factor that influenced a decision.
Software is documented to help the authors remember from day to day the subtle reasons behind choices. Easy to forget dependencies are specified. Why are they easily forgotten? Because the dependency is not obvious. An example of this is the dreaded global variable. A global variable available to multiple processes and or threads can cause difficult to trace errors if the global variable is not properly guarded. Clear documentation of the global variable is needed. Naming conventions to help one identify a variable of global scope are a common "best practice" in development. Some have felt that it is impossible to manage the global variable and banned the use of them in code. They feel there is no amount of documentation that can be in place to protect against global variable errors. Why is there no amount of documentation that will suffice? Because people do not read documentation.
Software is documented so that the authors of the software do not have to repeatedly instruct how to deploy the software. Software does not run in a vacuum. It has to have an initial state specified. That state may be simple or complex. Software systems work with other software systems to utilize external resources, pass messages, and provide resources. There are identification settings such as IP addresses and user names. There are credentials that must be setup. It would be impossible for the author of a piece of software to recall of the settings necessary to properly configure a system.
Software is documented to help people unfamiliar with the system develop a correct understanding of the system. A new computer scientist may be hired and given the task to continue work on an existing system. Without a thorough understanding of that system any changes can result in side affects that may are may not be readily noticed. The logic of the system will soon find itself riddled with code that addresses each unique bug that is introduced and the state of the system so that the bug can be avoided. Simply said, the code will soon be filled with if statements concerning the state of the system. "if (pageCount > 3) then ResetFootnotes();" What caused the problem with the "footnotes" in the previous example? A lack of understanding of the complete system. This understanding could have been gained from adequate documentation.
For code you document at least two things. One thing is the usage of the method or the class. This documentation is synonymous to the users manual only for the programming audience. The second thing you document is the reasons for coding the solution in this way.
The reasons behind the choices made during development are critical, not the simple restating the code in English. The reasons capture choices and explicitly define dependencies.
Finally for code, you may want to comment an algorithm by restating it in a human language (as opposed to a computer language) if the audience may be less experienced then the original author.
Through the application of the idea that "the product itself captures the current state" then most of the documentation will explain reasons for the implementation, express attributes that are not defined by the product (such as configuration settings), and provide usage tutorials.
Since people do not read documentation then why document? Also, since the code changes and the documentation are not updated to reflect these changes then why document?
Why do people not read documentation? Why won't a man ask directions when he is lost? Why will a woman ask a man how he feels when she knows he has no feelings on the matter? We might as well ask, "Why do people do stupid things?" Ok, I go a little far here. I will pull my thoughts back in a bit. People don't read software documentation because they assume they know how the system works already. They do not intend on working under misconceptions and creating problems. They may have heard a description of the system that was not complete. They may have developed something similar before and felt they could leverage the basic understanding of the problem.
Another reason is that the person did not intentionally ignore the documentation. They just didn't know there was any documentation. They did not know where to find the documentation. What a shame to spend the time to create documentation and then not provide a way to locate it.
Since code changes so fast that the documentation is useless after one or two iterations or modifications to the system. Incorrect documentation is frustrating beyond belief. If you have ever studied some documentation and designed an enhancement around this information only to find that the documentation was wrong (whether incorrect or just lacking) will cause you to never want to waste time reading documentation again. Because of this programmers say, "The code is the only thing that can be trusted." This statement is true, plain, and simple. The problem lies in the fact that there are so many ways to implement the same algorithm that you might not recognize what the code is doing. With some languages such as C++ you can change the meaning of common operators that are assumed to behave in a certain way. Just reading the code will not expose the true code path that is executed nor reveal dependencies and side affects. I know some say, "Yep, C++ allows for to many problems and doesn't protect the programmer from them self. But we have C# and Java now and we are safe!" We maybe be shielded from certain types of problems but we are not by any means safe!
So, if you are not going to keep the documentation accurate then why bother. Communication can not occur and there will be no benefit and in fact there will be detriment to those that use the inaccurate documentation. Remember, the goal is communication, and not just any communication but accurate communication.
Code as documentation is documentation for the adept programming audience. Any trick used in the code must be understood by the audience. It is documentation by programmers for programmers that are equal or superior. Any one else will not understand.
When deciding on how to document software the audience must be identified. If the documentation has to do with the implementation then it must be decided on the level of the audience. If the audience is a junior programmer than the code documentation will have to explain details that would not be necessary for a senior developer. Isn't it amazing how the best programmers are used to develop the system and the "others" are relegated to maintaining the system. The code is very likely complex and uses aspects of the language that only years of experience could understand. Then, this highly optimized and well crafted piece of software is left to a less experienced person to maintain. Without documentation for that audience the maintenance engineer is well on his way to failure.
User's manuals clearly have the user as the audience. Configuration documentation is for the deployment team and I.T. department. Whatever the audience, the documentation should be in terminology that is accurate and understood.
I really like this question because it is fundamental to the entire software development experience. Software is always being changed. Why? Because it wasn't enough, or better said, sufficient for the task. Why? Because application and audience changes. It is the same with software. People doing documentation should get a slight feel for the day to day life of a programmer. In one of my favorite movies, a version of Tombstone, Wyatt Erp says, "I'm coming after you and hell is coming with me." Well, in software, "change is coming and hell is coming with it."
The documentation is sufficient if it accurately represents the object and is stated in a vocabulary suitable for the audience. As soon as the object changes the documentation is not sufficient. As soon as the audience changes it is not sufficient.
Once it is identified that the documentation needs to be changed one should ask, "Is it worth changing?" It is the same in programming. You hear the developers saying, "That will take a re-write." That means that the software is not worth changing and it needs to be replaced. Maybe the documentation needs to be replaced. There may be a new way to communicate that did not exist at the time the original documentation was created.
This question is not the mechanics of documentation but more about the medium of documentation. User's manuals come in the form of books, tapes, interactive CD programs, videos, and hired trainers. Yes a person can be "documentation".
Recently digital cameras are used to capture parts of the development process to document the thoughts and work that lead up to a certain point. These cameras replace those fancy scrolling/printing white boards.
Be creative and use whatever means you discover to be efficient. Maverick development is about getting to the goal, not about the path to get there. Maverick development is not religious. There may be only one road to heaven, but there are many roads that get you to Rome.
For years my friend Dan Jarvis and I have talked about writing a real programmer's IDE. It would have views that would display information in many varied ways. It would allow for the pasting of diagrams, pictures, sound clips, and video in the code itself and these items would be considered comments by the compiler. I could go back and find our specifications for this IDE that we made in 1993 and I am sure that 90% of what we wanted is still not part of a development IDE.
I have said for years, "If I could only have a diagram of this object at the top of this file!" A picture really can say a thousand words.
UML diagrams, flow charts, etc., that are part of the design and are at a higher level then the implementation do not get out of synchronization with the code as often as implementation comments.
Wikkies and BLOGs could be used to document a software project. These tools are not new and their application to software documentation seems obvious.
People are the key to all of Maverick Development Models and Methodologies. In the documentation game, people play the most important role. When documenting a system it is often a goal to create a method of prediction so that when a similar task is performed estimates will be more accurate. All of the documenation in the world does not replace the value of the person that has the experience. Suppose you have a team that develops product "A" and the entire process is documented so that the process is reproducible. Then you lay-off the team that developed product "A". A few years down the road you decide to develope product "B" which is very similar to product "A". You hire a new team and they pour through the documentation of product "A". The new team's estimates for product "B" will not be as accurate as an estimation made by the original product "A" team. Experience captures and embraces the entire experience of developing a product. Experience trumps documentation every time. I would like to see a cost benefit analysis of keeping a team because of experience versus the cost of creating a documented process and assigning or hiring team members as needed. I wonder if business really saves money with all of the documentation (and its related costs) and the training of the team instead of keeping all of those high paid experienced engineers.
Accurate communication to the desired audience is the goal of documentation. Code is documentation that is for a very specific audience. If a broader audience is going to have to understand the documentation, in this case the code, then it will have to be tailored for that audience. You could either write the code to the lowest common denominator of those reading the code or you could use comments and other forms of documentation. Having senior engineers limited to writing code that a junior engineer could write is a waste of money. Fire the senior engineer and hire a bunch of junior engineers! If you are going to send your code off-shore for maintenance then you need to ask yourself if your native language (for example English) will work at the off-shore site (such as China).
Use your imagination on how to document the software system. Text documentation comes from a time when that was all that was available. Use the technologies that are now available. Videos, sound clips, digital photos, presentation software, charts and graphs, Web Logs, Wikkies, whatever best communicates to the audience.
Remember that experience trumps documentation. Keep your employees around for a long long time.