Documentation Cannot Compile Run Or Do Useful Work

When writing documentation, especially DesignDocumentation, I have the same feeling I would get if I wrote 50,000 lines of Java in MS Notepad, showed it to a few people (so that they can argue about my punctuation style), and (later, much later) tried to compile and run it. What do you know? Code written that way would never compile, run, or do useful work.

Documentation is a sort of error-ridden prototype whose errors and glories are equally mysterious.

Let me add that documentation is largely an unscoped effort. There is no clear indication of "done-ness." The result is the effort is largely driven by an end date and the number of bodies thrown at it.

I disagree with this - I believe documentation is the most important output that a programmer can produce. Programming is knowledge creation, and implicit in knowledge creation is its transmission to other people. It does no good to create a whiz-bang product if nobody knows what it can do. It's even worse if nobody knows what it can do and nobody knows the internals well enough to extend it.

Lack of documentation is the #1 factor that prevents me from using 3rd-party software. If it's missing a feature but well-documented, I at least know how to frame on a request on the project's mailing list. If there's no starting point at all, I'll just go elsewhere or write up a solution myself. Java's comprehensive, well-organized JavaDoc give it a huge advantage over Haskell, Ocaml, Ruby and CommonLisp, and a fairly large one over Python and PHP.

The scope of documentation is pretty well-defined: you're done when other people can understand your project well enough to use it and modify it. Unfortunately, that requires thinking about people rather than machines, something anathema to many programmers.

I share your distaste for DesignDocumentation, though. At design time, you don't understand the problem space well enough to communicate anything, as you are (by definition) still exploring it. Usually that understanding comes more easily from a few prototypes or a SpikeSolution, which also gives you a better base to work off. But there's no excuse for not going back and writing some design documentation after the product design has stabilized. -- JonathanTang

I use lots of software that has very little documentation. As long as I can read the source I can understand what it does. Code that has documentation but does not come with source is often so difficult to use that it is practically useless. The latter includes a lot of Java code documented with Javadoc and the .NET SDK documented with the .NET equivalent.

I believe the first sentence in this section is a major exageration. Clearly, a working program is the most important thing that a programmer can produce. Documentation without code is valueless. The question is what is the value brought to the code by the documentation, and what is the cost of creating that documentation. The cost includes both the direct labor in producing the documentation as well as the lost value of code not developed because of the resource shift from coding to documenting.

I thought about that when I wrote this, but I'm not entirely certain. Consider the following two situations:

A programmer writes a great program. He finishes it completely and wipes all the bugs out. He does not write any user documentation nor programmer documentation. Assume (for the sake of argument) that he did not write SelfDocumentingCode.
A programmer writes a terrible program. He does not finish it, and it does not work at all. He thoroughly documents his approach, his assumptions, the code he already has, dead-ends that he's run into, and the user requirements and how they relate to his design. Assume (for the sake of argument) that he is on the right track.

Both programmers then leave the company.

If I were a business owner, I would rather be in situation #2. At least then I could hire another programmer and he would have a starting point to go from. He would be aware of pitfalls in the problem domain, and approaches that have been tried already but don't work. And he has a goal to shoot for.

If I were in situation #1, the replacement programmer would likely have to start from scratch.

Obviously, the exact cost/benefit depends on a lot of other factors. If programmer #1 wrote a reasonably good UI, you could likely use the program even without documentation, and even a partially-useful program trumps no working code at all. It's also highly unlikely that such a great programmer would write code that is not SelfDocumenting?, or that such a mediocre programmer would be on the right track. But the page is about documentation's value relative to code, not great programmers' value relative to mediocre programmers.

The equation also changes as the organization scales. If you have 1000 great programmers, all of whom write great code and no documentation, you have a mess (Netscape? Symbolics? Microsoft). If you have 1000 great documenters, all of whom write great documentation and no code, you at least have a lot of information for your SkunkWorks of 10 people to use or ignore. And your userbase will love you. -- JonathanTang

Documentation should explain decisions taken and not taken. Why an approach, architecture or algorithm was selected, and what others were considerd and rejected. Which requirements or user stories have been included,etc. Why, not what.

This information is not in the source code, but without it arguments and decisions will happen again and again as more people come into contact with the code, ask the same questions, and get no answers.

It seems to me that when people on this wiki discuss "documentation" they are often talking past each other. There are several types of documentation:

How to use the code (as a user)
How to interface to the code (as a programmer)
How to modify the code (as a maintainer)
How to develop the code (as a developer)

Clearly these are separate issues, but they seem constantly to be mixed. What architecture, approach or algorithm was used is of little interest to a user, of moderate interest to on interfacer (for want of a better word) and of potentially critical interest to a maintainer.

Perhaps this page should be re-read, asking in each case which type of documentation was being assumed. I'm sure they're not all the same.

If your documentation contains properly formatted usage examples and their output, DocTest runs those examples with the current codebase and compares the outputs.

Note that above there are four classes of people who may be assisted by professionally written documentation:

Developers - Documentation about what is to be developed and such mundane things as specifications, responsibilities, and scheduling of deliverables
Programmers - Documentation about what the programmer is to code, what dependencies and relationships might exist between programmers involved in differing aspects of the code ( code primarily involving execution, other involving interfaces and physical presentation and display of input and output requirements to users
Maintainers - Documentation concerning library of functions, their operation and dependencies, etc., to the end of compartmentalization and structural definition.
Users - Documentation as to what one may encounter in the use of the product, tutorials, indexes, screen shots, detailed descriptives of what one is to provide as input and how, and what can be produced as output of use to the user.

The documentation for each of these classes of people should be written by professionals acquainted with the particular skills and needs of the targeted reader. Often they will be separated in time and distance from the coding effort, being viewed as training and informational resources rather than as merely definitions and operational characteristics.

-- DonaldNoyes.20111031

AprilZeroSix