Forgot your password?
typodupeerror
Programming Software IT Technology Linux

Creative Documentation 136

Posted by CmdrTaco
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?"
This discussion has been archived. No new comments can be posted.

Creative Documentation

Comments Filter:
  • Yes.... (Score:3, Insightful)

    by UncleTogie (1004853) * on Monday August 06, 2007 @04:04PM (#20133799) Homepage Journal
    ...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 (Score:2, Insightful)

    by clusterlizard (1136803) on Monday August 06, 2007 @04:06PM (#20133839) Homepage
    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 (Score:1, Insightful)

    by Anonymous Coward on Monday August 06, 2007 @04:07PM (#20133849)
    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.
  • by xxxJonBoyxxx (565205) on Monday August 06, 2007 @04:09PM (#20133875)

    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 (Score:5, Insightful)

    by rueger (210566) on Monday August 06, 2007 @04:12PM (#20133911) Homepage
    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.
  • by fm6 (162816) on Monday August 06, 2007 @04:19PM (#20133991) Homepage Journal
    ...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.
  • by WK2 (1072560) on Monday August 06, 2007 @04:21PM (#20134013) Homepage
    That is called a tutorial. Tutorials are a great resource, especially for beginners. It is also important that tutorials are accompanied with "reference" material.
  • by Control Group (105494) * on Monday August 06, 2007 @04:26PM (#20134085) Homepage
    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... (Score:4, Insightful)

    by ItsLenny (1132387) on Monday August 06, 2007 @04:28PM (#20134117) Homepage
    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 (Score:3, Insightful)

    by gEvil (beta) (945888) on Monday August 06, 2007 @04:36PM (#20134221)
    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?
  • by Control Group (105494) * on Monday August 06, 2007 @05:02PM (#20134519) Homepage
    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.

One small step for man, one giant stumble for mankind.

Working...