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

Pffft, Old Hat

[Fx.Dr]

If you compile the Anarchists' Cookbook you wind up with Windows 3.11 for Networking.

I thought my Linux education was going well...

[Rob T Firefly]

...until I was eaten by a Grue.

Re:I thought my Linux education was going well...

[plover]

One of the problems will be in what some people consider "funny". Would you have read the documentation if it went like this?

Narrator: In A.D. 2007, virtualization was beginning.
LGuest: What happen ?
Machine: Somebody set up us the guest kernel.
User: We get host OS.
LGuest: What !
Operator: Main OS boot up.
LGuest: It's you !!
Hypervisor: How are you gentlemen !!
Hypervisor: All your kernel are belong to us.
Hypervisor: You are on the way to virtualization.
LGuest: What you say !!
Hypervisor: You have no chance to survive make your time.
Hypervisor: Ha Ha Ha Ha ....
User: Captain !!
LGuest: Take off every 'IO' !!
LGuest: You know what you doing.
LGuest: Move 'IO'.
LGuest: For great justice.

Q1. What is lguest?

[GillBates0]

Q1. What is lguest?
A. RTFM n00b.

docutainment

[croddy]

ctrl+f "docutainment" NOT FOUND?

WTF?

[Anonymous Coward]

Q: "Hey, how do I get this mission critical app running?"
A: "RTFM for teh win - it's a real hoot! I'm a level 2 warlock and member of the trade guild."

Documentation, even good documentation can be difficult enough to understand without 'puzzles'. Readers want answers to questions and solutions to their problems and quickly goddamnit.

wrong forum

[Joe Snipe]

here at slashdot we can't even rtfa, let alone rtfm.

Re:No

[bbh]

How did you get here? Are you lost?

Next Big Headline

[ReverendLoki]

Future Headline: Journalists try and mix humor, wit and puzzles in their writing in order to encourage /.ers to actually RTFA.

Summary Result: A bunch of disappointed journalists.

Re:Short answer: no

[plover]

Tech docs ... shouldn't be, read start-to-finish, any more than a dictionary should.

Aha! So that's why I know so freakin' much about aardvarks, but jack sh!t about zebras.

Re:Yes....

[gardyloo]

Agreed, and I try to work around it with the following question line to clients: "Say you have two drivers. One is familiar with the state Driver's Handbook and traffic laws, having read up on them. The other has just got behind the wheel for the first time. Which one do you think would get in more accidents, and why?" Whichever one ATI wrote.

Read the Documentation?

[Jeremiah Cornelius]

I'm like most of the people posting in a /. thread: I don't even read the flippin' article!

I am however, rapidly refreshing these same 3-4 browser tabs, hoping to watch the works of Shakespeare to eventually flash briefly past my weary eyes... :-)

You are in a dusty kernel driver directory

[billstewart]

A stairway called .. leads up.
A directory called "docs" leads down to the left.
There are files here.