Problems With Documentation

Documentation suffers from a number of potential problems:

Expensive, time-consuming; the cost of the documentation may outstrip its value
Written by people who can't write or who don't know the material
Hard to read; too dry, too terse
Vague; not clear
Incomplete
Assumes knowledge readers don't possess
Misleading (maybe even flat-out wrong)
Outdated
Unavailable; you can't find it when you need it
Difficult to maintain; when you need to change it, you can only find a paper copy
Used in lieu of fixing a problem
Used in lieu of understanding the system
PaperGivesNoFeedback
DocumentationCannotBeAutomaticallyChecked? (like AcceptanceTests, for instance)

Solutions to documentation problems:

Doing anything right is expensive and time consuming. Why should documentation be any different? Commit to developing documents as you commit to developing software or anything else.
Hire tech writers to back up the engineers. Don't try to turn engineers into tech writers or tech writers into engineers.
Document problems separately from the working system. A list of known bugs released with a product is okay, but trying to turn the user into a component of the development chain is not. Thus come the complaints about adding workarounds and "fine print" to the docs as opposed to fixing the durn problems in the first place.
Maintain documents just like you maintain code. If a product changes such that module interfaces change or the user's operation changes then that change needs to be noted.
DO NOT make significant (like, design-impacting) changes to the code before first making a change in the appropriate document. The code reflects the document, not the other way around.

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

Expense. A good technical writer can significantly decrease the cost of documentation. For example: On one development team, all the documentation is written by the programmers, of which there are twenty. On average, each developer spends four hours a week writing documentation of various kinds (internal, external, etc.), and they're each paid USD $40,000 a year. Working out those numbers, the company is paying USD $80,000 a year for documentation. A good technical writer makes about half that, and the documentation will be of better quality (all other things being equal).
Time. Ah, yes. The age old question: Why is there never time to do it <ahem>, "Write", but always time to do it over [fix the problems]? Time spent thinking about a problem needs to translate into something written down that describes both the problem and its solution. When a solution is attempted and fails then that, too, needs to be put into document form somehow. This stuff is too valuable to just forget (TheRoadNotTraveled).
Difficulty in addressing the needs of widely varying readers. Well, not really. I (MartySchrader) used to write for Motorola. My assignments were always directed at one particular audience for any single document. An installation manual was for the grease monkey in the company motor pool. A service manual was for the tech with a hot soldering iron. The user manual was for the guy who actually had to call his office. Each audience got a document aimed specifically at him. There was little overlap.
Getting out of date. Don't be a lazy bum and the docs won't get out of date. Look at the discussion under Time, shown above.
Relying too heavily on foresight (see objections on OnlyForesightMatters). This is one of the most specious arguments around. Of course documentation relies on foresight -- because you've done all the heavy lifting even before typing in the first header invocation. This is true whether the piece of work at hand is a 20 line function or a 1000 page system. Either way you need to prove to yourself that you know what you're doing before you try to do it. The XP side of this is writing tests first, then code to meet the tests. Heh.
People don't like to read even if it's good documentation. Well, people are lazy bums, what can you say? Are these the same people who don't want to look at source code to figure out how to use a class, method, or application? Tough toenails, Charlie. You have to read something -- why not a professionally written API document?

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