Sunday, December 27, 2009

Documentation Is Not Like Code

I find it very difficult to write good documentation for the X-Plane scenery system and tools. Not only am I not a technical writer by training and not particularly good at explaining what I am thinking in non-technical terms, but since I have been working on the scenery system for over five years, I don't really have good perspective as to what is complex and what is straightforward.

For this reason, I try to keep my ears open any time an author cannot understand the documentation, cannot find the documentation, or in another way has a problem with the scenery website. These "first experiences" give an idea of the real utility of the docs. Writing a reference for people who know things is not very hard - writing an explanation for new authors is much harder.

One author who was converting from MSFS to X-Plane pointed out a problem with the documentation that I hadn't realized before - but I think he's on to something. He pointed out that the information you need to complete a single project is often spread out all over the place. You probably need to look at an overview document, a file format, and a tool manual, each of which describes about 1/3 of the problem. To make it worse, each document assumes you know what the other ones say!

Who would write such poor documentation? A programmer, that's who. (In other words, em.) In computer programming, the following techniques are all considered good design and essential:

Breaking a problem into smaller, sections.

Limited cross-references between these sections as much as possible.

Keeping the sections independent.

Not duplicating information (code).

In other words, the docs I have written for the scenery tools are a mess because they are "well factored", a good thing for a C++ and a really useless thing for humans.

This is definitely not the only problem with the documentation, which also suffers from a lack of clarity, is often incomplete, and could use a lot more pictures. I am a programmer, and I am paid to make X-Plane faster, better, etc. It can be very hard to find the time to work on documentation when the next feature needs to be done. And yet...without documentation, who can use these features?

Now that I've at least figured out that factorization is bad, for the short term I am going to try to write "non-factored" documentation. The first test of this will be MeshTool. I am doing a complete rewrite of the MeshTool readme. Like the ac3d readme, MeshTool needs a full large-scale manual of perhaps 10-20 pages, and the task needs to be approached recognizing that the manual is going to contain a huge amount of information.

When I work on the MeshTool manual I will try to approach it from a task perspective, with explanations of the underlying scenery system, rather than a reference perspective that assumes authors might know why the given techniques work. We'll see if this creates a more usable manual.

7 comments:

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 :)

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!

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.

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.