Comments on: Documentation Is Not Like Code

By: Wayne Conrad

Wayne Conrad — Wed, 30 Dec 2009 19:22:25 +0000

When dinosaurs roamed the earth, software docs came in two pieces: A user manual, and a reference manual. The user manual was a tutorial or overview of the software, usually having an introduction and then chapters that might be, for example, "Starting xyz" "Saving your work" "Interfacing xyz with foobaz," etc. It would not cover every feature, but it covered in broad strokes what the software could do with enough detail to be useful to someone wondering just how it could be used.

The reference manual was organized by command, or opcode, or etc., and listed in great detail what each piece was, with all of its options and details of how it worked. You weren't expected to be able to learn how to use xyz from ground zero if you only had the reference manual, but it was the go-to place once you knew how to use it and were looking for details.

In language terms, the reference manual was like a dictionary, and the user manual like a grammar guide with some sample sentences.

I wonder if that split isn't still a good idea not just for the user, but for the author.

By: Benjamin Supnik

Benjamin Supnik — Tue, 29 Dec 2009 08:52:31 +0000

Not Counting On Miracles – I nuked your post due to _language_…if you want to rant about Austin, please do so without four letter words.

By: Anonymous

Anonymous — Mon, 28 Dec 2009 19:41:08 +0000

I'm thinking of updating my FSX KML scenery tool to work with XPlane so
updated documentation will be much appreciated!

Regards, Matthew.

By: Anonymous

Anonymous — Mon, 28 Dec 2009 09:52:00 +0000

Usually, one hunts for the Eureka line all over the web, and not just the documentation. Like the keystone of an arch, when the Eureka line is missing, nothing will work; the picture is not whole. And yet, the Eureka line is the one most often assumed to be too obvious to mention.

By: Steve

Steve — Sun, 27 Dec 2009 18:04:48 +0000

Ben, this epiphany is a godsend to all X-Plane hobbyists – an excellent holiday present, if you will. I know this is a bear, I've had to translate code into human concepts too. User-think is a whole 'nuther world from Developer-think. It will take time…but if this becomes the way of things with Laminar, X-Plane will only grow faster. Cheers, and good luck!

By: Anonymous

Anonymous — Sun, 27 Dec 2009 14:42:57 +0000

How many computer people does it take to change a light bulb?

30 - One to analyse the existing light bulb installation, one to specify the new installation, one to implement it, five to beta test and twenty-two to write the damn documentation!

Seriously though, as a coder who worked in education I can sympathise. Your docs have to contain all the necessary information working on the assumption that the end user knows absolutely nothing while managing not to sound patronising - It is never easy. Good luck :)