Beta

Slashdot: News for Nerds

×

Welcome to the Slashdot Beta site -- learn more here. Use the link in the footer or click here to return to the Classic version of Slashdot.

Thank you!

Before you choose to head back to the Classic look of the site, we'd appreciate it if you share your thoughts on the Beta; your feedback is what drives our ongoing development.

Beta is different and we value you taking the time to try it out. Please take a look at the changes we've made in Beta and  learn more about it. Thanks for reading, and for making the site better!

Creative Documentation

CmdrTaco posted more than 6 years ago

Programming 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?"

cancel ×

136 comments

Pffft, Old Hat (5, Funny)

Fx.Dr (915071) | more than 6 years ago | (#20133783)

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

Re:Pffft, Old Hat (0)

Anonymous Coward | more than 6 years ago | (#20133869)

*Workgroups, rather, but all the same.

Re:Pffft, Old Hat (0)

Anonymous Coward | more than 6 years ago | (#20133929)

Except Windows 3.11 actually worked, reasonably well by standards of the time.

The Anarchist's cookbook is a bunch of junk that doesn't work. Its own author disowned it as a bunch of silly crap he just heard and never actually tried.

Re:Pffft, Old Hat (0)

Anonymous Coward | more than 6 years ago | (#20134109)

He should have used the stuff against those pesky brats who are always trying to steal his Lucky Charms!

Re:Pffft, Old Hat (0)

Anonymous Coward | more than 6 years ago | (#20135099)

Can it execute by dynamic binary translation (DBT) instructions that don't exist in a real CPU?

By example, if a aplication if compiled for Core Duo with SSE3 instructions then the soft-hypervisor can translate the SSE3 instructions for its execution in a real old i486.

Is it a good idea, not?

Can translate the 0-1-and-3 rings?

Read the Documentation? (2, Funny)

Jeremiah Cornelius (137) | more than 6 years ago | (#20135571)

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... :-)

Yes.... (2, Insightful)

UncleTogie (1004853) | more than 6 years ago | (#20133799)

...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....

Re:Yes.... (3, Interesting)

value_added (719364) | more than 6 years ago | (#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) [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:Yes.... (1)

UncleTogie (1004853) | more than 6 years ago | (#20134947)

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 an intern of ours started working here, he'd ask question after question. I'd answer the tricky/ambiguous ones, but if he stumped me or asked something he SHOULD know, I'd smile and reply: "I'm not sure, but you'll be able to tell me tomorrow after you check tonight, won't you?" He invariably had the answer the next day...


...and now he's now one of the most capable die-hard Linux admins you'd want to see....

Re:Yes.... (4, Funny)

gardyloo (512791) | more than 6 years ago | (#20135249)

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.

Re:Yes.... (4, Interesting)

Oliver Defacszio (550941) | more than 6 years ago | (#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.

I thought my Linux education was going well... (4, Funny)

Rob T Firefly (844560) | more than 6 years ago | (#20133805)

...until I was eaten by a Grue.

Re:I thought my Linux education was going well... (0)

Anonymous Coward | more than 6 years ago | (#20134365)


That's nothing. I thought was a past-master of AmigaOS when I learned all that time I was meditating in error.

Re:I thought my Linux education was going well... (2, Funny)

plover (150551) | more than 6 years ago | (#20134729)

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.

Re:I thought my Linux education was going well... (0)

Anonymous Coward | more than 6 years ago | (#20135397)

lol, mod parent up

Re:I thought my Linux education was going well... (1)

cralewyth (934970) | more than 6 years ago | (#20135855)

Well, I just read it right there.

Hey..... what if we simply put all the documentation into slashdot comments? It'd be brilliant!

Re:I thought my Linux education was going well... (1)

Ohreally_factor (593551) | more than 6 years ago | (#20135139)

You must have come across this:

{
/* Wildcard not in map but now is */
- if (wild & (CHE_OK || CHE_UPDATED))
+ if (wild & (CHE_OK | CHE_UPDATED))
                source->stale = 1;
        }
        pthread_cleanup_pop(1);
 
- if (wild & (CHE_UPDATED || CHE_OK))
+ if (wild & (CHE_UPDATED | CHE_OK))
            return NSS_STATUS_SUCCESS;
/* It is pitch black. You are likely to be eaten by a grue */
    }

Re:I thought my Linux education was going well... (1)

Ohreally_factor (593551) | more than 6 years ago | (#20135793)

OK, this is just getting weird. Who knew that grue was part of the BSD userland?

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)

NAME
       grue, egrue, fgrue - print lines matching a pattern

SYNOPSIS
       grue [options] PATTERN [FILE...]
       grue [options] [-e PATTERN | -f FILE] [FILE...]

DESCRIPTION

       The grue is a sinister, lurking presence in the dark places of the earth. Its favorite diet is adventurers, but its insatiable appetite is tempered by its fear of light. No grue has ever been seen by the light of day, and few have survived its fearsome jaws to tell the tale.

OPTIONS
       -E
Eaten by a grue

[ohreally_factor~:] ohreally%  n
It is pitch black. You are likely to be eaten by a grue.
[ohreally_factor~:] ohreally%  n
Oh, no! You have walked into the slavering fangs of a lurking grue!

   ****  You have died  ****

Why? (1)

Tom9729 (1134127) | more than 6 years ago | (#20133817)

I think the first question that comes to my mind is why? If the documentation was "so good" in the first place and people didn't read it, what makes them think that making it into an adventure game will make more people read?

It's certainly creative, but creative isn't always good...

Re:Why? (1)

ephesus (252335) | more than 6 years ago | (#20134689)

Well, differing opinions are always welcome. On the next project you release, you can document it any way you would like.

Q1. What is lguest? (4, Funny)

GillBates0 (664202) | more than 6 years ago | (#20133819)

Q1. What is lguest?
A. RTFM n00b.

Re:Q1. What is lguest? (1)

Provocateur (133110) | more than 6 years ago | (#20135815)

I think I have found the cause of the so-called elitist attitude that outsiders have so often accused us of. It's in the kernel, and those seemingly harmless comments like the one above whiz by but subliminally plant themselves while we watch the boot messages scroll speedily by. Faster boot times matter not, but the rest of us that go and grab a cup of coffee during the boot process are less harsh (e.g. RTM! F***in n00b!) on IRC and in the forums.

Uh how about reality as the 'new' adventure (1)

monkeyboythom (796957) | more than 6 years ago | (#20133831)

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:Uh how about reality as the 'new' adventure (2, Insightful)

WK2 (1072560) | more than 6 years ago | (#20134013)

That is called a tutorial. Tutorials are a great resource, especially for beginners. It is also important that tutorials are accompanied with "reference" material.

Ah, my old Apple //c (2, Interesting)

ArcherB (796902) | more than 6 years ago | (#20133833)

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.

Re:Ah, my old Apple //c (3, Interesting)

Mr. Fahrenheit (962814) | more than 6 years ago | (#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?

I do some writing (2, Insightful)

clusterlizard (1136803) | more than 6 years ago | (#20133839)

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.

docutainment (2, Funny)

croddy (659025) | more than 6 years ago | (#20133841)

ctrl+f "docutainment" NOT FOUND?

Great (1, Insightful)

Anonymous Coward | more than 6 years ago | (#20133849)

Turn shitty documentation into nerdy poems and puzzles. It's already a puzzle and full of stupid 'wit'. The last thing I'm going to want is documention be adapted to Monty Python or tired Douglas Adams' jokes.

Go play with Clippy then. N/T (1)

someone1234 (830754) | more than 6 years ago | (#20134213)

Go play with Clippy then.

Hell no. Just make sure I can search it. (3, Insightful)

xxxJonBoyxxx (565205) | more than 6 years ago | (#20133875)

Will making documentation more entertaining actually work to get people to read it?

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?):

At this point it's not immediately obvious what we're supposed to do next. ...quick grep of the driver's makefile reveals that it was a very big hint

No (0)

Anonymous Coward | more than 6 years ago | (#20133891)

Non geeks still don't care.

Re:No (1)

ItsLenny (1132387) | more than 6 years ago | (#20134021)

non-geeks probably wouldn't be able to read past the first page anyways... make Preparation ... BLAH!!

Re:No (2, Funny)

bbh (210459) | more than 6 years ago | (#20134025)

How did you get here? Are you lost?

With apologies to the Talking Heads (1)

sconeu (64226) | more than 6 years ago | (#20134533)

And you may ask yourself
"How did I get here?"

Re:No (0)

Anonymous Coward | more than 6 years ago | (#20134611)

No, we come by to laugh at you.

Re:No (0)

Anonymous Coward | more than 6 years ago | (#20134839)

No, we come by to laugh at you.
Which just proves that you don't really have lives either.

Documentation (5, Insightful)

rueger (210566) | more than 6 years ago | (#20133911)

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.

Re:Documentation (1)

digitalderbs (718388) | more than 6 years ago | (#20134609)

clear, complete and timely.


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:Documentation (1)

thePsychologist (1062886) | more than 6 years ago | (#20135471)

I agree completely. Documentation needs to be clear without any extra frills like stories and poems.

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 like more guides and tutorials to be as entertaining as possible, while still having the basic boring trusty documentation to go back to when I need it.

Nothing new under the Sun... (1)

khb (266593) | more than 6 years ago | (#20133915)

One of my earliest computing experiences was at JPL who had massively hacked their Univac environment. The documentation was, of course, rewritten in house. I can still remember a variety of Univac commands, not beaccause they were so obvious, but because the documentation was so good.
@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? (1, Funny)

Anonymous Coward | more than 6 years ago | (#20133931)

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.

Visual Studio 2005 (1)

Nom du Keyboard (633989) | more than 6 years ago | (#20133935)

Microsoft desperately needs this guys -- or somebody -- to rewrite the Visual Studio .NET/2003/2005 into something usable. Considering how easy the VS 5/6 help files were to use, I've never understood how they were able to take such a giant leap back into almost complete un-usability. One is ready to believe conspiracy theories regarding that MS has a secret state in all the VS manual publishers who try to explain what Microsoft itself doesn't!

Re:Visual Studio 2005 (1)

plague3106 (71849) | more than 6 years ago | (#20134343)

Hmm, I've found the .Net help to be better than help in vb6.

Re:Visual Studio 2005 (1)

eggoeater (704775) | more than 6 years ago | (#20134955)

Correct. It's called MSDN [microsoft.com] ... and now that they've gotten the MSDN2 site fixed it seems to have everything for all three versions of VS.


Re:Visual Studio 2005 (1)

TheVoice900 (467327) | more than 6 years ago | (#20135779)

I hope you're kidding. The documentation for Visual C++ 6 was in many places flawed, and sometimes just downright wrong. I pity any developer who ever tried to use any of the provided example codes. Many of them contained glaring bugs, extremely insecure coding practices, and some didn't even compile!

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 (1)

Mr. Bad Example (31092) | more than 6 years ago | (#20133969)

> man lguest

A hollow voice says "Fool".

Re: Creative documentation (1)

morgan_greywolf (835522) | more than 6 years ago | (#20134219)

> lguest --help

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! (1)

Jonah Hex (651948) | more than 6 years ago | (#20133983)

Happy Ending: You have successfully started your lguest and now are running linux on linux! Huzzah!

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 (1)

SolusSD (680489) | more than 6 years ago | (#20133987)

forcing someone that wants documentation to see the sourcecode is great! especially since wanting to read this kind of documentation usually means your a capable programmer.

wrong forum (3, Funny)

Joe Snipe (224958) | more than 6 years ago | (#20133989)

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

If you need entertainment... (2, Insightful)

fm6 (162816) | more than 6 years ago | (#20133991)

...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.

Knuthiness (1)

daigu (111684) | more than 6 years ago | (#20133999)

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.

Much documentation is just bad (0)

Anonymous Coward | more than 6 years ago | (#20134005)

If I could understand the bleeping man page, I wouldn't need to read the bleeping man page!

I've seen pages so bad that I bet the author himself couldn't use them a year after writing them.

I'd just settle for decent documentation most of the time. Heck, I've seen documentation so bad that it was easier to read the source code to find out what I needed to know.

Re:Much documentation is just bad (0)

Anonymous Coward | more than 6 years ago | (#20134733)

My personal gripe on Linux is that half of the man pages point you to the info documentation.


Info is the most irritating to use documentation system I have ever had the misfortune to use. I can type "man " on OpenBSD, FreeBSD, Solaris and AIX and get a halfway decent and reasonably coherent man page. I don't understand why the same can't be achieved on Linux.

Attention getter (1)

Puls4r (724907) | more than 6 years ago | (#20134007)

In the world of daily releases, I suppose everybody is desperate to get folks attention. It's a cute way to do it - but not much more.

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 apache on my windows machine. 20 seconds to download, 1 minute to install, a couple of simple questions and it was running. THAT is the way things should work.

Re:Attention getter (1)

koxkoxkox (879667) | more than 6 years ago | (#20134137)

Well, we're talking about a low-level driver here. Some things just can't be that simple. A good doc is always extremely useful when you want to understand something, not just use it.

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:Attention getter (2, Insightful)

Control Group (105494) | more than 6 years ago | (#20134519)

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.

Documentation is funny that way... (3, Interesting)

Anonymous Coward | more than 6 years ago | (#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.

Re:Documentation is funny that way... (1)

DerekLyons (302214) | more than 6 years ago | (#20135331)

That's probably because 95% of all computer documentation is utter crap.

Short answer: no (1)

blueZ3 (744446) | more than 6 years ago | (#20134059)

Longer answer:

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: first, at install time to install and configure and second, when a problem arises and the user needs to find an answer. Neither of these is really helped by adding puzzles or poetry. If you want to read/write that kind of stuff, take a night class in English Lit.

The things that get users to "read" a document are unrelated to the content and the factors that make documents useful are a logical structure, a good TOC, and complete index.

Re:Short answer: no (1)

Control Group (105494) | more than 6 years ago | (#20134127)

But you're talking about a different goal. Tech docs that are designed to be good at answering specific question aren't, and shouldn't be, read start-to-finish, any more than a dictionary should. But docs that are designed to introduce you to something should be, and there may be a role for creative writing in that instance.

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 former.

Re:Short answer: no (1)

RobBebop (947356) | more than 6 years ago | (#20134259)

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 frequently thrown errors are "Catch-all" statements that something outside the software in question is screwed up.

Re:Short answer: no (3, Funny)

plover (150551) | more than 6 years ago | (#20134309)

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.

That depends on your audience (3, Insightful)

Control Group (105494) | more than 6 years ago | (#20134085)

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.

Re:That depends on your audience (1)

plover (150551) | more than 6 years ago | (#20134595)

A good design document based on use cases can make a really good starting point for the "why" document. If a use case titled 'Load guest kernel' doesn't mean anything to you, you're probably not the target audience for the document, let alone the product itself.

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 most detailed minutia of their tools. He came back to us at the end and proudly said "So, what do you guys think of the online courses?" I felt bad telling him that they were almost useless, because I didn't know when or why I'd want to do any of that stuff. I may not know what the hell a subordinate change request document is, when I'd want one, why I'd need one, who would request one, or what I'd type on one, but I sure know how to create one. I asked him if he documented the use cases (meaningful things like "Request a Build") but I never heard back from him.

Re:That depends on your audience (1)

Control Group (105494) | more than 6 years ago | (#20134973)

Agreed - use cases are a good place to start. But I don't see any reason you can't make the use cases themselves somewhat more entertaining than a bland list of bullet points and screen shots. It's also helpful if the use case document goes into some detail (but not too much) about why you're performing each step, and the ramifications of doing things differently.

Of course, that kind of documentation is hard to write. I'm certainly no good at it.

Perhaps a better question is: (1)

Burz (138833) | more than 6 years ago | (#20134095)

How to make a more inviting Linux platform for endlessly creative application programmers?

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 (2, Funny)

ReverendLoki (663861) | more than 6 years ago | (#20134111)

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... (4, Insightful)

ItsLenny (1132387) | more than 6 years ago | (#20134117)

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

Stupid (1)

DogDude (805747) | more than 6 years ago | (#20134131)

This is painfully stupid in more ways than I could count. Stupid idea. Bad writing. Not even remotely entertaining or funny, even if you do know all of the uber-dork references.

A lot of geniuses... (1)

WK2 (1072560) | more than 6 years ago | (#20134145)

Sometimes, the best ideas seem like bad ideas at the time. It is important that the creative people with these ideas continue with them, even if they are ridiculed. Otherwise, we would have missed out on some of the best inventions.

That being said, intentionally making documentation more difficult is just stupid.

Not creative, not helpful (1)

athloi (1075845) | more than 6 years ago | (#20134155)

It was creative when James Joyce did it. Maybe. But throwing in all sorts of different styles, puns, mysteries and so on is a trivial act. It's not the equal to writing documentation so good it becomes definitive. It's more like being "creative" by being random, which ends up being cute but not really effective.

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. I want them to be able to find information quickly and get out.

Making reading the documentation "an art" won't do that for them and it will slow them down and force them to spend more time on the documentation, which no one (even documentation authors) likes to do.

Doesn't work... (1)

techiemikey (1126169) | more than 6 years ago | (#20134163)

I found myself looking over it to what it was talking about even in the first paragraph

Huh? (1)

SuperBanana (662181) | more than 6 years ago | (#20134193)

The article summary makes it sound like the kernel is superbly documented but nobody reads the documentation. That's a nice little myth.

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. (3, Interesting)

ravyne (858869) | more than 6 years ago | (#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.
 

Re:Something to be said for it. (1)

Chris Burke (6130) | more than 6 years ago | (#20135837)

Heh, nice. I had a prof who would do the same thing for his AI class homeworks. There wasn't some backstory behind it like with the Green Sarge and Evil Physics Monkey. Each homework though would have a theme and have problems that described the adventures of characters ranging from Marvin the Martian to Marvin the Depressed Robot. While the actual grunt work was just as boring, it was nice to get a few yuks out of a homework assignment when spending a late evening in the computer lab.

Okay, so that isn't actually that much of a "range". Hopefully the organic AIs reading this will infer a broader spectrum than characters named "Marvin", unlike the learning algorithms of the class which would not!

I did have a physics professor who loved to use stuffed monkeys in physics demonstrations. What is it with physicists and monkeys?

ummm, yeah (2, Insightful)

gEvil (beta) (945888) | more than 6 years ago | (#20134221)

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?

Wikipedia (0)

Anonymous Coward | more than 6 years ago | (#20134241)

Maybe they should start by creating a wikipedia page describing what lguest is. I've become so used to finding a wikipedia page for almost everything - each one starting with a description answering to the question "What is it?" - that I'm totally lost if there's no such page.

There's one for xen and kvm, why not for lguest?

As usual (1)

hcdejong (561314) | more than 6 years ago | (#20134257)

it depends. By all means make it an interesting narrative. But don't expect the user to read the entire manual. Most people will use the manual as a reference, looking up only the section they need. The manual needs to be usable in this case as well.

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 (4, Interesting)

dgp (11045) | more than 6 years ago | (#20134265)

the king of off-beat technical documentation is Why's Poignant Guide to ruby [poignantguide.net] .

missing target (1)

Jeek Elemental (976426) | more than 6 years ago | (#20134305)

For documentation in general, I wish it could be targeted more to the likely reader.
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 (1)

hcdejong (561314) | more than 6 years ago | (#20134311)

If you expect your audience to be non-native speakers, you've got to be very careful with your language. Word play, slang, cultural terms (incl. sports metaphors, for example) are hard to translate and many non-native speakers won't understand what you're saying. This is an issue both when you're supplying just an English manual, and when you get a translator to create a localised version of the manual.

Ruby? (1)

notorious ninja (1137913) | more than 6 years ago | (#20134333)

will making documentation more entertaining actually work to get people to read it?
see: http://poignantguide.net/ruby/ [poignantguide.net]

For fun? yes. For work? not really a choice there!

*Phew* plain text (1)

El_Muerte_TDS (592157) | more than 6 years ago | (#20134363)

The last documentation I read needed a Z machine interpreter.
Took me hours just to get through the maze.

Yes, but... (1)

sxeraverx (962068) | more than 6 years ago | (#20134419)

Yes, but does it run Linux?

The documentation is where it belongs! (1)

ChaosDiscord (4913) | more than 6 years ago | (#20134481)

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 author has done is place his documentation in comments with the code; perhaps the most obvious place for it. The "make Preparation!" and friends simply extract and collect the documentation scattered around the code into a single place, sort of like Doxygen, JavaDoc, or any of a pile of other documentation systems.

That the documentation contains some mild humor is irrelevant. Does it convince people to read it when they wouldn't have otherwise? Probably not. But it can lighten the mood for both author and reader, inspiring people to read on a little more. It can help relax the reader and make them more receptive to the ideas presented. I'd be suspicious of any non-trivial code base completely free of humor; suggests someone operating on the mistaken belief that programming must be Serious Work, the sort of person who ignores basic human behavior and thinks people can behave like robots.

Just tried it... (1)

Sprite_tm (1094071) | more than 6 years ago | (#20134485)

...It seems to be a sort of script which can output various comments and sourcecode lines in a certain order. I think the technical part is nicely done: in this way, you can get a neat walkthrough of how the code works with the up-to-date, real code interspersed with the documentation. For example: if the routine can use a certain macro, the script can be written to explain the macro directly from the header file in which is defined. That's nice, I always hated to look them up myself. (So, for the people who didn't get this before, it is not a real text adventure, it's just that some passages are written realy adventure-ey.)

Apart from the technical details, the documentation itself is nicely done, too: while the stuff that's discussed is kinda hard to digest, the nuggets of humour that can be found made me want to find the rest too. I agree that these aren't really necessary if you, for example, are paid to create a patch to the lguest-system, but it can be useful for people who just want to mess with the code: easier-to-read documentation will make less of these people give up and more, hopefully interesting, patches will be developed.

If any, it was a nice way to learn about a basic virtualisation-implementation. I for one am a bit more knowledgable after reading it.

Re:Just tried it... (1)

rusty (3244) | more than 6 years ago | (#20136203)

Hey, I'm glad you liked it.

From reading the comments it seems most of the /. crowd are not the intended audience. This is not user documentation (that's in Documentation/lguest) but programmer documentation for those delving into the source, and it assumes some degree of famliarity with the Linux kernel too.

Feedback welcome!
Rusty.

The Fortran Coloring Book redux (2, Interesting)

davidwr (791652) | more than 6 years ago | (#20134503)

Anyone else remember The Fortran Coloring Book [gwu.edu] by Dr. Roger Kaufman back in the '70s?

That was some entertaining documentation. Or rather, an entertaining tutorial.

Re:The Fortran Coloring Book redux (0)

Anonymous Coward | more than 6 years ago | (#20135133)

Yes! It's awesome. Both funny and instructive. I used to recommend it regularly to people who *had* to learn FORTRAN, and were not looking forward to doing so. It made the task much more fun, and it really is an effective book for teaching FORTRAN from scratch.

Depends on audience (1)

quacking duck (607555) | more than 6 years ago | (#20134513)

If you're a technie trying to get the thing running, then no. Obviously we need to know the features, options, caveats, etc., both in a linear/chapter form (e.g. how to install and maintain system), and we need a good search system to find specific things in the documentation.

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, never mind a full manual. They have better things to do, and I don't blame them.

Make it *interesting* though, and you have a lure to hook them into learning. Just like tricking a kid into learning by making it fun, it works with adults too. Don't make it as condescendingly stupid as "it looks like you want to write a memo, can I help?" but when dealing with non-technies, I find that if real thought and effort has been spent making the material appealing to learn, they're more willing to stick with it and actually retain what they learn. Screenshots and call-outs of items being discussed is a good start, and obviously the limit in print material; non-tacky animation and interactivity improves things greatly for online materials.

Perhaps more cynically, make user-oriented electronic documentation more like a TV show or movie--it's the only thing that'll stick in their memory these days.

Why is this a bad thing? (1)

Karl0Erik (1138443) | more than 6 years ago | (#20134853)

Why are people complaining about this? It's not like the normal documentation was eaten by a Grue. Like it or not, some people learn better by playing. If this helps people learn at all, it's a good thing. Those of you afraid of the grues can have your documentation and read it anyway.

Funny, but .... (1)

ryry (198300) | more than 6 years ago | (#20134869)

Disclaimer: IAATW (I am a technical writer) at a mid-sized SW/HW engineering company. The problem is not getting the user to read the docs. The problem is making sure they find the appropriate information once they're in there.

Most users hit the docs only when they encounter a problem. In that case they might crack a smile at a haiku in their doc set, but ultimately I bet that those nonstandard forms of writing would impede the comprehension of the material. As someone else here pointed out already, you know the docs are counter-intuitive when you have to pause for "a few moments of thought" as far as where to proceed next in the docs.

I hate to be a killjoy, but: Get in, read a couple lines, and get back to your app - that's the goal. Anything else is a distraction (at best) and a waste of time (at worst).

However, the article makes the point that "the humor and wit sampled above is only a tiny fraction of what's included, as the documentation itself is often actually quite technical and certainly useful." (I take this to mean that the humor is present in only a tiny fraction of the overall documentation set.) This design might show that the documentation author himself set appropriate limits on the humor :-)

Hmm (0)

Anonymous Coward | more than 6 years ago | (#20135077)

"Will making documentation more entertaining actually work to get people to read it?"

Maybe, maybe not. But it would at least (for somebody like me) make *writing* the documentation a much more enjoyable experience. I'm a solution architect at the moment, I have built something of a reputation around here for adding silly photos and captions to my architectural documentation - mostly taking the piss out of the project team (us and the customer!). I really enjoy making people laugh and it makes a rather dry, boring document rather more palettable.

Who reads the manuals? Who reads the man pages? (2, Interesting)

rjschwarz (945384) | more than 6 years ago | (#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.

Well.. (1)

JRHelgeson (576325) | more than 6 years ago | (#20135327)

It appears to be working... I mean, when was the last time you read an article that was written about product documentation?
(Would this be considered meta-data?)

-joel

"eye"-guest or "ell"-guest? (1)

DogAlmity (664209) | more than 6 years ago | (#20135583)

Can a brother get a serif over here?

what is really needed in the way of docum.... (1)

3seas (184403) | more than 6 years ago | (#20135961)

...documentation is simple and direct, common and consistent format that can also be used to apply at least examples (doing is half of learning process).

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 part of the problem is one of lingo, terms used, etc.. For example there is Dbus which uses backward urls and file like paths and "methods".... But would the typical everyday thinking person think in terms "I method you to do this" or "I method the computer to send it to you...

Why not just say "I gobalnegat dagondeha yogaznicondi..you too"

The point is, so long as there is "geek-n-speak" to complexifabulicate intent, there are going to be documentation problems of users lacking interest. Typically starting with "What do you mean by.... "computational thinking"?

Load More Comments
Slashdot Account

Need an Account?

Forgot your password?

Don't worry, we never post anything without your permission.

Submission Text Formatting Tips

We support a small subset of HTML, namely these tags:

  • b
  • i
  • p
  • br
  • a
  • ol
  • ul
  • li
  • dl
  • dt
  • dd
  • em
  • strong
  • tt
  • blockquote
  • div
  • quote
  • ecode

"ecode" can be used for code snippets, for example:

<ecode>    while(1) { do_something(); } </ecode>
Create a Slashdot Account

Loading...