Documentation is an important part of any application. So, don't forget to include it when generating new applications or modifying existing ones.
If you are a programmer or analyst who must move between different versions of the same language (i.e. Microsoft Visual C++, Borland C++ Builder, and GNU C++) one of the most obvious of differences is the documentation. Since the formation of Microsoft, documentation has been a weak area in the eyes of the user. Today, Microsoft has not changed this image one bit. One only has to look at the documentation for Visual C++ 2008 to confirm that this company definitely does not learn from its' mistakes.
When creating a custom application, a similar mistake can be made. As a programmer your job is to pound out code as quickly and as bug free as possible. However, even the most brilliant and clever programmer can be made ineffective if the code generated is not adequately documented. To understand this, one must look at application generation from the system point of view. Application systems are usually managed by customer IT personnel who have the responsibility to oversee the work and maintain it when the initial coding is completed.
It is rare indeed that new applications do not have logical errors in the code (Editors Note: logical errors are not syntactical errors). It is often the job of customer IT staff to find and correct logical errors in newly installed applications. Later, functional changes may be made that require generation of new code to add to or patch the original application. Even the best of programmers will find it difficult or even impossible to modify or support code that has poor or non-existent code documentation.
This is an area marginally enforced on new projects. Programmers are contracted to generate working code, and little or no attention or instruction is paid to documentation. The well seasoned programmer will place comments within the code they write in order to act as a reminder of the line of thought used when the code was generated. With experience on the project, a programmer will often re-code a section of code (or in some cases, a whole module) when given the vision and experience of having the application near completion. The comments serve as pseudo-code for new code or regeneration of the original. Much later customer IT staff will find these comments invaluable in understanding the code stream and researching problems and logical errors.
External documentation is usually about the user. Every user must know what to do in order to use the application the way it was written. This documentation will often reveal logical errors and point out functional deficiencies that would otherwise go unnoticed until much later. External documentation is generated by someone other than the programmer. This is for a very good reason. Programmers are by habit and nature task oriented with very narrow focus. Writers for external documentation must have the user perspective in order to develop user documentation that is clear, concise, and usable.
There is a mantra that is true today just as it was 20 years ago - “You can never over-document an application”. Even if you don't find some documentation useful today, there may come a time when it will be a lifesaver (or job saver).
