Andy Oram recently posted a very interesting article on the O'Reilly Radar on how to improve online documentation. It's a very insightful analysis of the problems that face those writing documentation.
He suggests two tools should be implemented on any online documentation effort:
- Quizzes
- Cross-reference management
He recommends each documentation page include a simple quiz at the end. This is to help monitor quality. If readers aren't answering a question right, this probably means that section of the documentation needs improved.
His second point addresses the twin problems that documentation is hard to find, and when it is found, often times it is useless because you lack the necessary background to understand the material (an experience I'm very familiar with).
He suggests two solutions to these problems:
- Making it easy for readers to suggest prerequisites and follow-up documents
- Generating paths through documents so the potential reader has an entire syllabus
Read the rest of the article:
http://radar.oreilly.com/archives/2008/01/two_tools_we_ne.html
What do you think? Are his suggestions useful to our efforts? How could we implement them?
Comments
Making documentation more useful
That was an interesting article, but from my own experience with online documentation feedback forms, such as the "Was this page helpful" that Microsoft and Google use, I find that many users will not use the quiz because they are just searching for the magic pill to solve a specific problem.
That said, I think the Handbook styled documentation that is used on the Drupal network is probably a good candidate for this type of quiz feedback that Andy described. The reason being that the documentation may be used for training purposes by a organization that is training its tech team how to implement Drupal. Now, we are approaching the realization of free education on the Internet by improving the quality of that information; and perhaps, the user community is beginning to realize that when they find a good document it is in their best interest to provide helpful feedback to the author. At the same time making sure that the information is useful, the user will also ensure that they understand what they just read, and help ensure the quality of future docs.
As for implementation of a quiz / cross reference styled feedback form for the Drupal association site, I am not sure if that is where this should be implemented; but rather, this system would be more suited to the other sites in the network that host the Handbooks and tutorials.
good points
you make some good points. I clicked this thread hoping to read some good stuff about good approaches to making the documentation more useful, but I tend to agree - based on my own personal experiences.
--
mike stewart { twitter: @MediaDoneRight | IRC nick: mike stewart }
New URL for this
New URL for this article:
http://radar.oreilly.com/2008/01/two-tools-we-need-to-improve-o.html