Creative Documentation

FuriousCurio writes "Linux kernel hackers appear to be an endlessly creative group of individuals. In response to previous documentation attempts not having been read by many people, KernelTrap is reporting about how the lguest documentation was prepared to be something of an adventure story. Self-proclaimed to turn you into an lguest expert, lguest being one of the new solutions for running a virtual instance of the Linux operating system as a user process within a real instance of the Linux operating system, the documentation mixes humor and wit into puzzles, poetry, and of course source code and a low-level understanding of virtualization. But the questions remains, will making documentation more entertaining actually work to get people to read it?"

Comments

Hell no. Just make sure I can search it.

[xxxJonBoyxxx]

Will making documentation more entertaining actually work to get people to read it?

Hell no. Just make sure I can search it when I get stuck.

Even the author of TFA thinks this doc is crap (you need "grep" to get off the first page?):

At this point it's not immediately obvious what we're supposed to do next. ...quick grep of the driver's makefile reveals that it was a very big hint

Documentation

[rueger]

Should be clear, complete and timely.

Every time I've tried to solve a linux problem I've run into docs that miss one, two or all three of those things

Documentation has to be very clear, very unambiguous, and very specific. When you're already up against a problem you don't want to be guessing at what the docs are trying to tell you.

Looking at TFA, my suggestion to not waste everyone's time with cutesy games - hire a real professional to write and edit your docs and get them right the first time.

That depends on your audience

[Control Group]

There are two purposes to documentation: one is to serve as a reference. That is, when someone who is generally familiar with the system needs to know how to do a particular thing (be it design a cursor, add a command line switch, locate a config file, apply an update, or whatever), there needs to be a document that can be used to easily find that particular answer. This is the goal being striven towards (largely successfully) by man pages.

The other purpose, however, is to make someone who is completely ignorant of the system familiar with it. Most software documentation is terrible at this. Telling me how to do something isn't helpful if I don't know why I'd want to - or, worse, don't even know that such a thing can be done.

Since I haven't used a bad car analogy in a while: having a document that explains how to install a cold-air intake on my car is useless if I've never heard of a cold-air intake.

What the lguest docs are trying to do is solve the latter problem. They're trying to take a system that someone doesn't know anything about (aside from just enough to be interested in it at all) and get that someone up to speed in a general way.

"How" is a good question to answer, but so are "why" and "what." Gimmicky documentation isn't necessary or desirable for the first, but may very well be both for the second and third.

I still think...

[ItsLenny]

Wiki's make the best manuals

when properly implemented

clear, concise, to the point, easy to search ..

and when new problems arise they're easy to add

With this you'd have to add a whole new realm or player class just to tackle the issue and stay with the theme