Documentation Anecdote

[Examples of AppropriateTechnicalDocumentation...]

So, we'd had a card for some time that said "I want all the code to be well documented", but it kept being given a low priority, so we never got round to it, until the other week. Nobody was very enthusiastic about doing this, especially after we had couple of hours workshop where we critiqued some existing comments in our codebase (mostly ones that arrived with the code, some of our own), and discovered how very hard it is to write comments that are even as good as useless, and how very easy to write ones that hinder, obfuscate and mislead the reader.

So we had a chat with the Customer, and it turns out that the requirement will be met if every public method on every public class is preceded by a comment. That is, is preceded by a comment at all. There is no requirement that the comments be useful, informative, or accurate. They just have to be there. That made me smile. I'm a vociferous opponent of commenting, mainly because I've so rarely seen any that fit into the first category mentioned above and consider that bad enough should be left well alone.

A little while after this episode I was pursuing my "personal development" work, trying to make sense of the example that came with an API I'm teaching myself. Unable to skry the thing out, I asked a colleague (and commenting fan) that I knew was fairly well versed in that same API for assistance. "Looking at the documentation, eh?" He asked, not without a certain smug twitching of the lips. "You'd think I'd know better" I replied.

But that got me to thinking: what I was looking at was not documentation in the sense that our comments are documentation. One might be forgiven for thinking so, since what I was looking at was unclear, imprecise, and inaccurate, the hallmarks of the type. But what I was reading was a tutorial.

With the tutorial was also a reference manual, and various overviews. They too don't seem to be documentation as the term is typically used of artifacts that support code. Or, as it is so used by programmers, anyway.

Those overview documents were especially interesting examples since they consist mainly of explanations of the forces that drive the design of the API, in this case the forces of high availability and small memory footprint. Those forces influence almost every feature of the API: the way object lifecycles are handled, the way error conditions are signalled, the way gui layout is specified. Almost every feature of that API is how it is to help resolve those forces. Which means that nowhere can any one feature have a comment that says so, if such a comment is not to mislead utterly. Either they all do, or none. Wisely, the authors of this API elected to have a separate document that tells the reader these things that are true of the whole package.

On DocumentationBeyondTheSourceCode mention is made briefly of the differing needs of different users of documents, but the point doesn't seem to have been taken up. Banging on about the evils of comments and the source code being the design and so on is more engaging.

Considering that point in the light of my recent experience as a use of documents in support of code, I find myself no longer really able to understand what this generic thing documentation is any longer. There are several kinds of document that can help in understanding some code that's new to you, tutorial materials with examples and exercises, overviews of the kind mentioned above, discursive materials that explain the history of the code and what decisions were made along the way to where it is now can be tremendously useful. But these lie at one end of a spectrum, and at the other are reference manuals of the full on javadoc type (ever seen a truly useful @param tag in the wild?), who's only benefit comes from being printed on so-versatile paper. And somehow, the bad odor of the latter has infected the former.

A few years ago I was involved in writing the chapter of the user's manual that covered the part of a product that I'd been working on. Working with the technical authors was very educational, moulding my knowledge of the working of the tool into the form required by the, as it happens highly technical but not software savvy, readership was hard but gratifying. That manual ( I wish I still had a copy) was not mere documentation, it was a document, well written, accurate and helpful to its readers.

Language can be a useful pointer to thought. So ponder this word "documentation". Chambers dictionary--which aims to be a catalogue of use rather than a supplier of definitions--tells us: documentation instruction (archaic); preparation, setting forth, or use of documentary evidence and authorities; documents or other materials provided in support, amplification or authentication; (in fiction) realistic reproduction of records, real or supposed; the written written information on the structure and operation of hardware or software (computing).

Look at that, we get a use all to ourselves! But aren't some of those other uses what good software documentation should be? Is? Who are we leading up the garden path? To my anglo-saxon ears, "documentation" sounds like an intransitive verb, and a pretty wooly one at that. Compare for yourself the affect provoked by "documentation", in the broader world, not just software, with that by "document". Lets not let ourselves get away with doing boring but comfortable documentation, lets write documents that we can be proud of.

Proof-Reading Failures

When proof-reading my own writing, often I don't spot a problem because my mind translates the pattern as I intended, not as I wrote it. For example, if I meant to write "Finding the Right Person for the Job..." but instead wrote it as "Finding the Right Pearson for the Job..." (note the "a"), there's a fairly high chance I'd miss it because the pattern of what I meant clogs my objectivity, even after multiple readings. I have to read practically each letter to catch such things. I haven't figured out a way to flush my head to read it as it actually is. Sometimes coming back to it a day or two later helps a bit, but is not always an option under tight deadlines.

That's an almost universal experience, it seems. The people in my writer's group all encounter it. Coming back later can help. Killing a tree (printing it out) and reading it paper can help. Send it to your ereader, and proof it there. Have other people read it. Even using a variety of tricks, I've still come back to something I wrote and edited 20+ times, only to find another error. OTOH, it seems that most books these days have grammatical errors, occasionally to the point where they're unreadable. -- DonBranson

Anecdotes:

I typed "To frank..." when I meant "To be frank...", despite reading the text 3 times. I got back replies asking, "Who's Frank"? Embarrassing. (I switched off the grammar checker because it gets too confused with tech terms and domain lingo--it's more noise than help.)