KludgeCode

is Ben Rudgers

Documentation is a Feature

The problem

As Alice in Wonderland {1}, I think about all the times I have chased around documentation structured where eggs links to bacon and sausage; bacon links to sausage and eggs; and sausage links to bacon and eggs and when spam is what I needed, and eventually it turns out on the one-hundred and seventeenth round trip, I notice that there is a link to spam right there at the bottom of the pages for eggs and sausage and bacon; hot linked in the phrase “Lobster Thermidor aux crevettes with a Mornay sauce, garnished with truffle pâté, brandy and a fried egg on top of spam.”

I have started thinking that part of the reason this happens is that hyperlinks are nothing more than GOTO, and sure, since GOTO is just JMP and JMP is fundamental to computing, there’s nothing inherently wrong with hyperlinks [or GOTO]. It’s just that circular GOTO constructs don’t fit with well with my brain’s bias toward pattern matching upon the obvious.

The other factor is not a product of recent thinking: open source documentation tends to be a ball of mud.

It has this tendency because it’s hard work to write and good documentation for a project of any significance and a lot less fun than writing code for people who write the code that requires all that documentation. The fun part is self explanatory, but the hard work is because good documentation looks more like the 2000 pages of GNU Emacs manuals or Knuth’s 1962 book about compilers than Java-doc. Good documentation is built around a narrative, or several narratives when there are multiple manuals, and each of these narratives is structured to have a beginning, middle, and end.

When the foundation document in a documentation project doesn’t have an appendix or two, it should be heeded as a warning not celebrated as a feather in the cap. Good documentation recognizes that there’s always something more to say, and tries to say it.

Documentation as a competitive advantage.

Four or five years ago when my father, whose early professional career entailed Algol on paper tape and ended using Wolfram’s SMP on Vax’s decided he wanted to learn word processing, spreadsheets and databases; I recommended he just purchase a copy of Office. Being Dad, this of course meant he chose Libre Office because it did everything he wanted to do. Technically, he was correct. The reason he went out and bought Office last year was because his local Barnes and Nobel and even Amazon had a poor selection of books about Libre Office, and more books about Office than there are trolls on the Internet [approximately].

This wasn’t surprising. He is a consumer of documentation and the right answer for him was pretty obvious to me. Being a similar consumer myself going back to the Amiga ROM Kernel Manuals. The quality of documentation is why I’ve decided EMACS is worth the effort of learning. It reminds me of the old hard bound reference manuals that used to ship with Auto-Cad. It was the quality of Microsoft’s documentation and its availability in hard copy that led me to stay on the Microsoft Stack until making a baby step to Racket and its above average documentation. The quality of Racket’s documentation is a byproduct of a writing culture it inherits from the academic world.

Apple is easy to write about

Though it is easier to write documentation for Microsoft products than for open source projects because there are easy assumptions about the context in which the reader operates. SQLserver, unlike MySQL, is only relevant with a narrow range of operating systems and under a few very similar licensing agreements and business models. MySQL could be running anywhere.

But nothing is easier to write about than Apple, it’s perhaps the reason why their devices are so popular with journalists. The reason is that Apple has established a ubiquitous language and this allows it to control the narrative. We talk about “App stores for Android” and despite the protestations, P. T. Barnum’s adage {2} that all that matters is if your name is spelled correctly holds true.

The Mozilla Conundrum

My list of great open source documentation projects is unfair. Mozilla’s documentation of all things browser related is phenomenal. It educates developers about the entire domain of which Mozilla’s projects form just a part. Unfortunately, it does not provide any momentum toward the adoption of Firefox. The decision to use Firefox is not made by the users of their developer portal. Decisions about Firefox are largely made one at a time by non-developers and usually based upon very few meaningful technical criteria.

For some software companies, however, “going Mozilla” and setting out to comprehensively document an industry segment, competitors and all, might provide strategic advantage. For a B2B oriented company based upon open source, documenting the larger domain demonstrates larger interest in helping potential customers find solutions to their problem irrespective of an established customer-vendor relationship.

A company providing a primary research resource for a larger market, above and beyond simply providing documentation for their own products, is able to honestly express the open-source ideals for a sound business purpose.

The fundamental ethic of the open-source movement is goodwill. The user must trust that the author is trying to solve the problem they say they are trying to solve. More interestingly, the author must trust that use of the software, in the worst case, causes the author no harm, and in better cases might just provide the author with some benefit. It is the ethic: we are not dividing a pie, your profit is not my loss.


{1} see Alan J. Perlis, Epigram 48

{2} Barnum allegedly said, “I don’t care what they say about me, just make sure they spell my name right.”