Slashdot Mirror
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?"
If you compile the Anarchists' Cookbook you wind up with Windows 3.11 for Networking.
...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....
Don't tell me to get a life. I'm a gamer; I have LOTS of lives!
...until I was eaten by a Grue.
Slashdot Burying Stories About Slashdot Media Owned
Q1. What is lguest?
A. RTFM n00b.
An Indian-American Hindu committed to non-violent thought/speech/action alarmed by the global explosion of radical Islam
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.
There is no "I disagree" mod for a reason. Flamebait, Troll, and Overrated are not substitutes.
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.
i took a bitchslapping for natalie portman
ctrl+f "docutainment" NOT FOUND?
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?):
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.
Three Squirrels
here at slashdot we can't even rtfa, let alone rtfm.
Sometimes, life itself is sarcasm...
...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.
That is called a tutorial. Tutorials are a great resource, especially for beginners. It is also important that tutorials are accompanied with "reference" material.
Write your own Choose Your Own Adventure. http://www.freegameengines.org/gamebook-engine/
How did you get here? Are you lost?
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.
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.
Reality has a conservative bias: it conserves mass, energy, momentum...
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.
09 F9 11 02 9D 74 E3 5B D8 41 56 C5 63 56 88 C0
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
----------
Trying to fix or change something only guarantees and perpetuates it's existence
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.
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?
This guy's the limit!
Will making documentation more entertaining actually work to get people to read it?
s -tank-manuals-unexpectedly.html
The Germans thought so:
http://www.darkroastedblend.com/2007/02/wwii-nazi
"All great things are simple & expressed in a single word: freedom, justice, honor, duty, mercy, hope." --Churchill
the king of off-beat technical documentation is Why's Poignant Guide to ruby.
Aha! So that's why I know so freakin' much about aardvarks, but jack sh!t about zebras.
John
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.
Knowledge is how to play a game, intelligence is how to win, wisdom is knowing what game to play.
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.
Reality has a conservative bias: it conserves mass, energy, momentum...
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.
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...
"Flyin' in just a sweet place,
Never been known to fail..."
Bill Stewart
New Fast-Compression-only CPR http://preview.tinyurl.com/dy575ks
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.
InnerWeb
Freud might say that Intelligent Design is religion's ID.
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.
Money for nothing, pix for free