Follow Slashdot blog updates by subscribing to our blog RSS feed


Forgot your password?
Programming Software IT Technology Linux

Creative Documentation 136

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:
  • Ah, my old Apple //c (Score:3, Interesting)

    by ArcherB ( 796902 ) * on Monday August 06, 2007 @04:06PM (#20133833) Journal
    I remember the manual and floppy that came with my Apple //c. The floppy was an addition to the manual and included little games to help you learn the system. I remember one where little apples, some hollow, some filled, that were rolling down a conveyor belt. You had to hit the right apple key (open or closed apple) depending on the apple that was rolling down the belt. I believe a bunny gave you the gave you tips (ala Clippy). I don't think I remember the manual being all that serious either. That type of creative instruction led me to actually RTFM and get to know the basics of my computer.

  • by Anonymous Coward on Monday August 06, 2007 @04:24PM (#20134051)
    As a documentation writer, I've learned from experience that 95% of any typical audience won't read the docs, no matter how many pictures you include, or how entertaining you try to make it. People, in general, just don't like to read, period. They'd rather call support or fumble around and try to figure it out on their own.

    The other 5%, though, read the docs so thoroughly that they'll find the tiniest mistakes or oversights. This basically means that the docs have to be perfect, even though only a fraction of the audience will bother to use them.

    Having thorough documentation still occasionally helps the other 95% though -- it gives the Tech Support guy something to point to ("see page 108 of the User Guide") when dealing with idiot questions from people who should know better.
  • by ravyne ( 858869 ) on Monday August 06, 2007 @04:36PM (#20134211)
    There's something to be said for the humor/wit approach I think.

    My college physics instructor used the same approach in writing his weekly homework assignments. Essentially, the year's homework detailed the exploits of "Green Sarge" (A real-life version of those plastic soldiers you find at the dollar store) vs the "Beige Chumps" and, later, his arch nemesis -- the Fez-wearing, scimitar-wielding Evil Physics Monkey. Even if the students didn't start the homework immediately, they would always read it to see what Sarge's next exploits would be, and the problem would be in the back of their mind ready to consume any spare brain-cycles. The humorous problems also lead to a lot of impromptu discussion about the problem as well, just talking in the hall or over a lunch table. I think it went a great way towards getting the students to embrace their homework.

    [from (vague) memory]

    Q) At what velocity must the Evil Physics Monkey fire himself head-on into the Green Army supply train in order to stop it? The Train has a mass of 80,000kg and is traveling at 50km/h. The Evil Physics Monkey has a mass of 100kg. The EPM's scimitar has a mass of 15kg, recalculate the problem assuming that the EPM has carried his scimitar into battle with the Green Army supply train. Assume structural and soft-tissue damages are not a factor.
  • by Himring ( 646324 ) on Monday August 06, 2007 @04:37PM (#20134235) Homepage Journal
    Will making documentation more entertaining actually work to get people to read it?

    The Germans thought so: -tank-manuals-unexpectedly.html []

  • by dgp ( 11045 ) on Monday August 06, 2007 @04:41PM (#20134265) Journal
    the king of off-beat technical documentation is Why's Poignant Guide to ruby [].
  • by davidwr ( 791652 ) on Monday August 06, 2007 @05:00PM (#20134503) Homepage Journal
    Anyone else remember The Fortran Coloring Book [] by Dr. Roger Kaufman back in the '70s?

    That was some entertaining documentation. Or rather, an entertaining tutorial.
  • by Mr. Fahrenheit ( 962814 ) on Monday August 06, 2007 @05:10PM (#20134617)
    At the risk of getting flamed into hell and back out the other side, I seem to remember reading that the Solitaire game that came with MS Windows originally ('way back when) was designed specifically to get people used to using a mouse, since up until that point, you had DOS at home and LIKED it that way! /a 'mouse'?! //wtf would I do with THAT?
  • Re:Yes.... (Score:4, Interesting)

    by value_added ( 719364 ) on Monday August 06, 2007 @05:11PM (#20134621)
    ...a point hit home by the success of the "For Dummies/Idiots" series. It's one of the selling points of the books

    I think the very readable For Dummies series of books hasn't reached the seemingly untapped potential of its target audience. ;-)

    Maybe someone with a better knowledge of history or who has studied technical writing can elaborate on this, but I believe it was the O'Reilly series of books that broke ground on changing the manner in which technical books were written from textbook-ish style to something more informal and entertaining.

    I'd guess there's more than a few books in the O'Reilly catalogue, for example, on everybody's favourite list, but the increasing focus on appealing to readers often leads to compromising on actual content. More people educating themselves by buying or reading more books (or on-line documentation) is A Good Thing, of course, but my preference has been for the (apparently dated) textbook-ish approach. Compare, for example, something like Internetworking With Tcp/Ip: Principles, Protocols, and Architecture (Internetworking with TCP/IP Vol. 1) [] published in 1991 with anything published today on the subject of networking. One is as comprehensive and as well written as it is boring to read, while the others are more accessible and topical and shorter. No surprise which sells more copies.

    What I've never got my head around is that people increasingly don't want to read anything. I wonder how somehow making their living as a writer feels knowing that most of us are guilty of relying on a Google search for a quick intro or how-to when the READMEs, man pages, source code, etc. is sitting on their hard drive.
  • Re:Yes.... (Score:5, Interesting)

    by Oliver Defacszio ( 550941 ) on Monday August 06, 2007 @05:45PM (#20135011)
    I wonder how somehow making their living as a writer feels knowing that most of us are guilty of relying on a Google search for a quick intro or how-to when the READMEs, man pages, source code, etc. is sitting on their hard drive.

    I am a technical writer, and I assure you that it's absolutely no secret that this is the case, and we're OK with it. I can't deny that there are times where I feel a little down after sweating blood over a documentation project that I know 16% of our customer base will ever read (that's an actual statistic, incidentally, from a firm I once worked for), but, in the end, my paycheck still arrives. I will say, though, that both companies for which I've worked as a writer are constantly working to improve documentation content and style in hopes that you'll use it instead of Google. Tech writing, despite how it probably appears, evolves like anything else. Whether its an effective evolution is up to you, I guess. I have my own opinions in that area.

    A much, much bigger frustration is the lack of respect given to tech writers by developers and hardware engineers. I couldn't count the number of times I've been handed a pile of "documentation" written by an barely literate ESL developer somewhere with the expectation that I can magically turn it into a public doc in "what, a day or two?" In their eyes, we're typists, and in the two years I've been doing this, one of my greatest professional joys has become the look on the face of some snarky developer when I say, "No, this is more like three weeks. Will that hold up your release?" As joyful as I am, though, there are times where I simply have to produce something in a quarter of the time it actually needs, and that invariably results in garbage. In my opinion, many of the problems with technological documentation could be solved by just keeping me in the loop throughout the project, but that seems to be too much to ask. On the rare occasion where this happens, I've produced award-winning manuals (yes, there really are awards for this) that receive a surprising amount of kudos from customers.

    But, most of the time, I'm handed junk information at the last minute and nobody's willing to answer the phone as I try to distill anything meaningful from the whole thing. Then, I either unapologetically delay the project or produce crap. The sun goes up, the sun goes down.
  • by rjschwarz ( 945384 ) on Monday August 06, 2007 @06:05PM (#20135199)
    Perhaps a manual is the wrong format for the information. Chunk it up into bite-size bits by topic and make it accessible from a command line instead of over there on the books shelf and you'll find Linux/Unix users reading the important bits. You'll find the manual/man pages grow in number because it's easier to write a three to four page chunk than an entire manual. So eventually it'll be like a Linux wikipedia in your distro with corrections and everything which are not really practical in an old style manual.
  • Re:Why? (Score:5, Interesting)

    by innerweb ( 721995 ) on Tuesday August 07, 2007 @12:21AM (#20138395)

    The concept is not new. It is called engaging the reader.

    For most of us on slashdot, we are already engaged by the technology. We have no other need to read the documentation. We want to know how to make this work just to know how to make it work. But, the average user could care less about how a thing works, so long as it does what they want it to without any need to learn if possible. Why do you think tutors and techs have so many jobs? Why do you think so many people have diseased computers? Because they are not engaged in learning about how or why it works.

    For those old enough to remember, the old TRS80 manuals were good examples of how to write engaging documentation in their day. We can do much better today, but few have done as well since then. People need an emotional tie when learning to truly remember. Think about those things you actually do remember from decades past. They almost all have an emotional anchor, whether it be tears or laughter or something else (excitement of learning?).

    So, creating a set of documentation that meets needs of people who do not get the same excitement/enjoyment out of just learning the tech will go far for helping the others out their learn the tech. And we need them to learn the tech. Or linux and OSS will die on the vine.

    You can always claim that as long as people can write software, there will be open source. I counter that until the general public has a vested interest that they are aware of and care about, OSS is always at the mercy of government and business. All it takes is a few laws to be passed and OSS goes away. Some are on the books now and some are talked about often enough here.

    The best way to fight for the future of anything is marketing. That includes *good*, solid, easy and friendly documentation. That may be the biggest selling point to the home user in the end. "It just works" is not just a slogan, but an expectation of most people. If whatever it is does not live up to that, then whatever claims to be next will steal their attention.

    It boils down to loud words mean nothing. Claims of ours is better means nothing. All that means anything is the average parent/sibling/child can sit down and just use it. If the docs are not fun and easy, then that is very unlikely to happen for most people.


  • Answer: Yes. (Score:4, Interesting)

    by richie2000 ( 159732 ) <> on Tuesday August 07, 2007 @04:40AM (#20139469) Homepage Journal

    will making documentation more entertaining actually work to get people to read it?
    Yes. I tried this out with the TenFour TFS Gateway manuals back in 1998. When I added humour to virtually all examples given, support incidents clearly went down. In spite of this, I was ordered to take them back out since they could be perceived as being "un-serious".

    An example from the cc:Mail section:

    The TFS post office can not be used for addressing. Mail sent directly to the TFS (gatelink) post office
    without having been addressed to a routing post office will go to e-mail heaven immediately. It would
    not be delivered if you put 40,000 volts through it.
    This was a big problem. People constantly addressed e-mail to the gatelink PO and they went in the bit-bucket. When I added that snippet to the manual, these problems went way down for new installs. I worked in support as well as doing the docs, so I knew the incidence rates.

egrep -n '^[a-z].*\(' $ | sort -t':' +2.0