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?"
Comment removed (Score:5, Funny)
Read the Documentation? (Score:3, Funny)
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...
Re: (Score:2)
Exit question: does this methodology seem more rational than contemporary US policymaking approaches? It certainly has the virtue of classical technology employment.
Re: (Score:2)
Yes.... (Score:3, Insightful)
Re:Yes.... (Score:4, Interesting)
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) [amazon.com] 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: (Score:2)
What I've never got my head around is that people increasingly don't want to read anything.
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?"
Of COURSE you get the ones that'll politely nod, and then go right back to what they're used to doing. It IS gratifying, however, to see that lightbulb flicker on every so often...
When
Re:Yes.... (Score:5, Funny)
Re:Yes.... (Score:5, Interesting)
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.
Re: (Score:2)
I couldn't count the number of times I've been handed a pile of "documentation" written by an barely literate ESL developer
If you only knew what we (developers) get from the clients in the first place! Just last week a manager 3 levels up from me asked for a sizing (price tag) on a system that was barely even an idea yet. But you know, this is not all of the problem. Another part of the problem is something that you appear to share with developers:
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.
I know this is a problem everywhere. The reality is, too little of this kind of work is aiming for end-to-end quality, but rather short-sighted focus on quarter-end commitments.
http [dilbert.com]
Re: (Score:3, Informative)
many of the problems with technological documentation could be solved by just keeping me in the loop throughout the project
I have on occasion had to more or less forcibly inject myself into projects just to be in the loop. I have also threatened the entire development staff with a baseball bat or simply coming around and sit on them (I'm fairly big) if they didn't give me useful data. It worked so-so - getting on the projects worked better, even though it took a lot of time from writing. It probably helped that I'm trained as a programmer originally and could actually contribute a little bit to the projects.
Re: (Score:2)
Why? Seriously, the web is the best possible place for documentation. Application documentation search (man, info, Windows help) is infinitely far behind any of today's web search engines, and considering the revenue possibilities, this is not likely to change. Other benefits (semantics, no need to compile, cross-platform) are left as an exer
Re: (Score:2)
Because companies think that the only correct representation of their product comes from within. They just hate, hate, hate it when you read some wrong information about their product on a public forum somewhere, then tie up an expensive Tech Support representative when you screw things up and have to call. And, frankly, they're right. Now, before you trot out the old chestnut about customer objectivity versus corporate policy, just thi
Re: (Score:2)
Re: (Score:2)
I thought my Linux education was going well... (Score:5, Funny)
Re: (Score:3, Funny)
Re: (Score:2)
Re: (Score:2)
Last login: Sat Aug 4 16:49:07 on ttyp2
Welcome to Darwin!
[ohreally_factor~:] ohreally% grue
tcsh: grue: Command not found.
There is no grue here.
[ohreally_factor~:] ohreally% man grue
grue(1) grue(1)
N
You are in a dusty kernel driver directory (Score:4, Funny)
Re: (Score:2)
Why? (Score:1)
It's certainly creative, but creative isn't always good...
Re:Why? (Score:5, Interesting)
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
Q1. What is lguest? (Score:5, Funny)
A. RTFM n00b.
Uh how about reality as the 'new' adventure (Score:2)
Basically, how about writing user documentation that captures real world scenarios and details from start to finish how a task, or better yet, an objective can be completed.
either that, or just turn it all into a first person shooter. I'll settle for either one.
Re: (Score:2, Insightful)
Ah, my old Apple //c (Score:3, Interesting)
Re: (Score:3, Interesting)
Re: (Score:2)
These things continue to this day, though. With the TouchStream keyboard, you got a game where you had to balance a ball on a surface by moving your hand across the keyboard.
Re: (Score:2)
I do some writing (Score:2, Insightful)
docutainment (Score:3, Funny)
Great (Score:1, Insightful)
Go play with Clippy then. N/T (Score:2)
Hell no. Just make sure I can search it. (Score:4, Insightful)
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?):
Re: (Score:2)
Documentation (Score:5, Insightful)
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.
Re: (Score:2)
Ideally, entertaining documentation should supplement standard documentation. However, I can appreciate that writing documentation can be very boring, and this would cause the doc writers (probably the programmers) to procrastinate on making the docs complete and timely -- especially when they're not payed. If this motivates the documentation writers (and secondarily, motivates the readers), then I'm in favour
Re: (Score:2)
Wrong. If you find that, then hire someone who knows how to do it. I suspect that those who find it "boring" just aren't willing, or lack the skills, to do the thoughtful and detailed work that is needed.
Re: (Score:2)
However, there's a difference between the essential documentation and supplementary instruction manuals.
The essential documentation needs to have everything in it and be clear and well organized, and hence it will be extremely boring. A supplementary instructional manual on the other hand like this one for Ruby [poignantguide.net] has the ability to capture the reader's interest in a way documentation can't.
I would very much lik
Nothing new under the Sun... (Score:2)
@pack rat ; @ prep school
But they kept it within reason. Turning the documentation into the equivallent of a game, with ppuzzless is just asking for even fewer people to pay attention
WTF? (Score:1, Funny)
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.
Visual Studio 2005 (Score:2)
Re: (Score:1)
Re: (Score:2)
Re: (Score:2)
Granted, my experience in 2005 isn't nearly as extensive as it was with 6, I've found far fewer of such problems there.
Re: Creative documentation (Score:2)
A hollow voice says "Fool".
Re: (Score:1)
You are in a maze of twisty passages that all look the same.
> n
You are in a maze of twisty passages that all look the same.
ARRRGGHHH!
Choose Your Own Adventure! (Score:2)
Sad Ending: You couldn't figure out the Manual, and are now hopelessly confused and not sure exactly what you've done to your machine.
Actual text may vary from above material, since I just made this shit up... Jonah HEX
i like (Score:2)
wrong forum (Score:4, Funny)
If you need entertainment... (Score:3, Insightful)
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.
Knuthiness (Score:2)
Noone ever read it. So this time I'm trying something different, using a bit of Knuthiness.
While Knuth is a genius and all, I don't think Knuthiness is Chinese for readable. He might want to look to a different model if his goal is to get people to read his documentation.
Attention getter (Score:2)
The point of doing things for other people is that they shouldn't need to read the manual. Apple's got it right. It just works. In the case where it doesn't - you've already screwed up. In that situation I want an easily-consultable index with simple pages numbers along with a step by step with screenshots account of how to get it working.
I recently installed apach
Re: (Score:1)
Anyway, I think it is a fun idea. I've always loved well-written documentation, when someone tries to explain a program but also to share his passion, sometimes explaining even things that are not necessary. I am thinking of "The TeXbook" by Knuth or "A User's Guide to the Z-Shell" by Stephenson for example.
Re: (Score:3, Insightful)
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,
Documentation is funny that way... (Score:3, Interesting)
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.
Re: (Score:2)
Short answer: no (Score:2)
I write tech docs in my day job, and frankly, "interesting" isn't going to solve the "problem" of users not reading the docs.
Part of my M.S. program was a research project about software document usage and the vast majority of users don't "read" documentation in the same sense that you read a narrative: start at the beginning and read through to the end, with spine-tingling chills, mystery, and adventure galore in the intervening chapters.
Software documentation is mainly used in two situations
Re: (Score:2)
Perhaps a distinction needs to be drawn between "documentation" and "tutorials." I think the goal of the creative documenting in question, here, is more regarding the latter than the for
Re: (Score:1)
I agree that "creative documentation" has its place as a teaching tool for people who are looking to get started in a particular new technology. A lack of documentation is a barrier for any new user who wants to "dig into" the code.
It is a very narrow-minded view that thinks documentation should list the error messages that the code throws when problems occur and provide easily Google-able codes to search for an answer. A lot of the time, even this fails because (and I'm looking at Oracle here) the most
Re:Short answer: no (Score:4, Funny)
Aha! So that's why I know so freakin' much about aardvarks, but jack sh!t about zebras.
That depends on your audience (Score:4, Insightful)
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.
Re: (Score:2)
We had a guy spend months preparing a bunch of online courses that gave step by step instructions on how to click here, drool there, drag this and drop that for some source code management product. He gave complete details on how to click on the
Re: (Score:2)
Of course, that kind of documentation is hard to write. I'm certainly no good at it.
Re: (Score:2)
EXACTLY! I'd go so far as to say being the "best" software is less important than being able to communicate what your software does and why people should use it. Most "smart" programmers (or more accurately, they thi
Perhaps a better question is: (Score:2)
So far, the endless appeals to fix what you don't like in the OS are causing almost all curious application developers (both budding and experienced) to get up and walk away. I believe this is a larger factor than the MS monopoly/network effect, and that the success of Apple supports my view.
Next Big Headline (Score:3, Funny)
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.
I still think... (Score:4, Insightful)
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
Stupid (Score:1)
A lot of geniuses... (Score:1)
That being said, intentionally making documentation more difficult is just stupid.
Not creative, not helpful (Score:2)
If someone handed this documentation to me, I'd send them back to redo it. Not because I'm an enemy of creativity, if one even considered this mess creative, but because I'm thinking of the end user.
Doesn't work... (Score:1)
Huh? (Score:2)
Hey Linus, do us all a favor: mandate that nobody can put an entry/option into the kernel configure system unless they write a help file entry for it, so that we can tell what the hell it does.
It's incredibly annoying that a number of kernel config parameters have absolutely zero documentation aside from (if you're lucky) a semi-descriptive name...
Something to be said for it. (Score:4, Interesting)
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.
Re: (Score:2)
Okay, so that isn'
Re: (Score:2)
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.
Well, the clear answer is 0.99C. After all, the question implies we want to stop the forward momentum of the supply train. It shouldn't matter if we cause a little reverse momentum too.
ummm, yeah (Score:3, Insightful)
Germans thought so.... (Score:5, Interesting)
The Germans thought so:
http://www.darkroastedblend.com/2007/02/wwii-nazi
As usual (Score:2)
Puzzles I'd avoid. I had a few textbooks that introduced new concepts using puzzles. Math textbooks were particularly bad in this regard. Left me stumped on more than one occasion, which is bloody annoying.
Why's Poignant Guide to Ruby (Score:5, Interesting)
Re: (Score:2)
On the other hand, 1st edition Programming Perl is so old (pre- Perl 5) that any information it contains is probably useless for anything other than entertainment
missing target (Score:1)
Just put a list of the skills required to understand the following documentation at the start, and concentrate on the issue.
Short and brutal
Not conducive to international use (Score:2)
Ruby? (Score:1)
For fun? yes. For work? not really a choice there!
*Phew* plain text (Score:2)
Took me hours just to get through the maze.
Yes, but... (Score:1)
The documentation is where it belongs! (Score:2)
A lot of posters are complaining that the author has been to clever, that it won't help convince people to read the documentation, that people shouldn't have to search for it. These posters need to look more closely at the situation.
Let's take a look for this super hidden documentation. Here's the opening, cleverly hidden as a comment as the very first thing in the file named lguest.c [kernel.org]. That seems a pretty freaking obvious place to put an introduction to the system. For all the article's spin, all the
Just tried it... (Score:1)
The Fortran Coloring Book redux (Score:2, Interesting)
That was some entertaining documentation. Or rather, an entertaining tutorial.
Depends on audience (Score:2)
If you're an end-user who's trying to learn to use the system, then the idea has potential. I know many techies are all about "read the f'ing manual" but seriously, many end-users won't bother even looking up the quick hint sheets, nev
Who reads the manuals? Who reads the man pages? (Score:2, Interesting)
Well.. (Score:2)
(Would this be considered meta-data?)
-joel
what is really needed in the way of docum.... (Score:2)
Everyone knows how to use a dictionary, an encyclopedia, and can figure out specifics of more common but slightly varying document structures like catalogs, etc...
The more common and consistent such a format is the faster people will pick up on what is communicated in the documentation.
An old style common format is the unix man pages...as an example.
Another
I'd be happy (Score:2)
Answer: Yes. (Score:4, Interesting)
An example from the cc:Mail section:
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.
Re: (Score:1)
Re: (Score:2, Funny)
With apologies to the Talking Heads (Score:1)
"How did I get here?"
Re: (Score:2)