Login  Register

Where documentation roams

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
1 message Options Options
Embed post
Permalink
Reply | Threaded
Open this post in threaded view
| More
Print post
Permalink

Where documentation roams

mojavelinux
Administrator
I was reading an article today by a developer raving about AsciiDoc [1]. Though his excitement about AsciiDoc was enticing, that isn't the interesting part. What's most interesting is the stark contrast he gives between an example of incredibly bad documentation and an example of documentation that's incredibly useful...and where you find each one (it will surprise you).

The incredibly bad documentation was created by highly paid professional writing heaps of senseless words to satisfy documentation requirements for a software application.

The incredibly good documentation was created by volunteers writing to help fellow gamers understand the landscape of a complex role playing game.

In the linked article, he summarizes the cause of the bad documentation quite well:

"Developers are playing to document approvers and having fun with the existence of the document and completely ignoring its contents."

I see an important lesson in this story. The existence of documentation (and content in general) does not make it useful.

When you write documentation, think about how it can help the reader succeed at something. If you don't see the value in what you are writing, cut it. If you don't see any value at all, start writing.

When people complain about the lack of documentation [2], they aren't asking for heaps of senseless words, but rather a walkthrough guide like the gamers have written for each other.

What other lessons do you see in the story?