Problems With Documentation

Documentation suffers from a number of potential problems:


Solutions to documentation problems:
Are there problems inherent to documentation that are not injected by people dealing with documentation such as engineers, managers, and writers?

All of the above problems can be overcome by people willing to do so. Most professional tech writers, for example, will be able to overcome all the problems enumerated so far that are on the writing side of things. Tools can print the documents improperly, or format them incorrectly. And people can cause many unintentional problems, but recognizing that fact doesn't help solve any ProblemsWithDocumentation. What is required is a dedicated, professional effort to make the documents a product unto themselves.

There is only one root problem with documentation: it won't fit into OnceAndOnlyOnce principle. Every feature exists in two places: in the software and in the documentation. So, documentation can get out of sync and be incomplete, outdated, vague, plainly wrong etc etc.

This has been discussed to death all over the CategoryDocumentation pages. Software is a byproduct of documentation, not a separate entity. The document changes, then the software which is a result of the document is changed to match. No problem.

It's not always that easy. Installation manuals and online help are not changed first; they are changed after the software is changed.

Installation manuals and online help are after the fact documents and have no effect on the development of software. Installation can be affected by changes in the implementation of code, we suppose, but the help should reflect only the designed-in features of the system. When a change occurs that reaches back into the design or operation then the user manual should be changed to reflect the new functionality. The software is changed in parallel to meet the requirements of the changed feature.
Contributors: BrentNewhall, MartySchrader

See: DocumentationPatterns, ReplaceDocumentation, ProblemsWithDocumentationDiscussion, DocumentationMustProvideValue

CategoryDocumentation

EditText of this page (last edited April 23, 2010) or FindPage with title or text search