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?"

Yes....

[UncleTogie]

...a point hit home by the success of the "For Dummies/Idiots" series. It's one of the selling points of the books, and the reason why our shop recommends the series for neophytes....

I do some writing

[clusterlizard]

of prose as well as program code. I get mixed results with the creative liberties I takes with comments. It depends on the environment I guess. In the big, formal corporate place I worked, the people generally didn't take too kindly to it. In more informal environments they get a kick out of it. If you're talking about the documentation for a project, I think I'd keep it straight. Who wants to plow through a bunch of shitty writing to understand a program? Technical docs should make it as easy as possible to find what you're looking for as quickly as possible.

Great

[Anonymous Coward]

Turn shitty documentation into nerdy poems and puzzles. It's already a puzzle and full of stupid 'wit'. The last thing I'm going to want is documention be adapted to Monty Python or tired Douglas Adams' jokes.

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.

If you need entertainment...

[fm6]

...go watch a movie. When a technical document tries to entertain, it's just distracting.

People don't resist reading technical manuals because they're boring. They resist because most of them are crap, full of confusing explanations and information that's disorganized, out of date, or just plain wrong. Easier to figure stuff out for yourself.

I can say these things, because I write those damn manuals for a living. I like to think my own work is pretty good, but I'm disgusted by most of what I see. And that's the stuff written by "professionals". The amateur stuff that passes for documentation in the OSS world is even worse.

Re:Uh how about reality as the 'new' adventure

[WK2]

That is called a tutorial. Tutorials are a great resource, especially for beginners. It is also important that tutorials are accompanied with "reference" material.

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

ummm, yeah

[gEvil (beta)]

So, you guys think that by making documentation that's already difficult to read even more difficult to read, that you'll get more people to read it? Can I have some of whatever you're smoking?

Re:Attention getter

[Control Group]

This is where the term "irreducible complexity" turns out to actually mean something.

That is, not all software can be made fire-and-forget that way. Most of the software the end user actually interfaces with, perhaps, but not much more. I'm a SQL Server DBA by profession*, and the idea of a DB server install that "just works" is almost incomprehensible, because the definition of "just works" varies so much depending on what you intend to do with it. Does "just working" include a backup strategy? It should, because if you don't have DB backups, you don't have DBs. But without knowing what kind of downtime tolerance you've got, what your storage architecture and capacity are, or how sensitive your inforamtion is, you can't have a sane backup strategy. Does "just working" include a security model? It should, because you probably don't want everyone in the world looking into your database. But without knowing whether users are logging directly into the server, or only applications are, you can't design a sane approach to security.

The same is going to be true of a lot of software. It's one thing to get it "working" in the sense that Apache is serving up pages, SQL Server is fielding SQL strings, or your ASA is blocking inbound connections. It's another thing entirely to get it working right - and the definition of "right" varies so wildly from circumstance to circumstance that it's, in my opinion, impossible to make it somehow simple (in the Apple sense of the term).

*Yes, you may feel free to make jokes about how maybe it would "just work" if I didn't use an MS product.