Documentation Must Provide Value

The primary issue with documentation is cost effectiveness. Is it cheaper to develop and maintain written documentation than to allow people to go to the source for information? [See Note 1]

In some domains, definitely. Many users cannot access the source code to their applications, and even if they could, would not be able to understand it. If a user of Microsoft Word wants to know the operators available in a Find operation, providing them with access to the C code for the Find function would not help them.

There may be short term cost efficiency if there are a high number of questions covering a small range of topics. This would permit well targeted documentation, but in the longer term it may be more efficient to resolve the underlying problem.

Not knowing what operators are available in a Find operation would certainly be a problem, but not creating a document which addresses this is not a solution, either.

If there are a high number of questions covering a wide range of topics, then the documentation effort becomes very broad, and it is unclear whether the documentation writer provides any advantage by playing surrogate questioner for the user.

A large number of questions covering a wide range of topics indicates that more than one document or a document composed of multiple sections is called for. Scope must be limited for document projects just as it is for any other development.

If there are a low number of questions covering a wide range of topics, then the efforts of documentation writers to cover the topic thoroughly may be more time consuming than allowing direct contact. The documentation writers will need to ask more questions than the users would generate.

A small number of questions may simply indicate that the users don't know the capabilities of the package; a concise but exhaustive description may be sufficient to answer unformed and unspoken questions even before they arise.

If there are a low number of questions covering a small range of topics, then the documentation writers have little information to focus their efforts. This may lead to broader than necessary documentation with little offsetting value.

A small scope does not mean a useless document. It is very possible that a FAQ, cheat sheet, or other miniature reference may prove valuable well beyond its original intended purpose.

It is not enough to create well-crafted documentation; the documentation must provide value.

This is a truism. And it is a truism because we could s/documentation/fraggles/g on this page and it would still make (almost) equally much sense. Each kind of document, written so that a particular kind of reader in a certain context can answer specific questions must provide more value over the lifetime of the product than it cost to write and maintain throughout the lifetime of the product. Whenever someone starts talking about "the documentation", see if they know what the binding of each of the variables given in italics are. If they don't, then cost accounting isn't going to help.

For a great many products the cost of the documentation is a complete non-issue; for instance, in Class III medical devices the FDA will simply not let a product be certified without certain documents, so the cost of creating and maintaining those docs is secondary to their existence in the first place.

This argument is contradictory. It states that the documentation is required for product certification, hence the benefit is high. As the benefit exceeds the cost, the documentation would appear to be the most cost effective solution.

Please define benefit. We seem to, once again, be drowning in a sea of semantics.

NOTES:

Cost effectiveness is not the "primary issue" with documentation in most of the world.

See: ProblemsWithDocumentation

CategoryDocumentation