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.
...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
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
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
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.
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.
-
Inventor of the term 'pardon my French'.
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.