A few months ago, someone tweeted about a book from Sun Microsystems called Writing in the Open: Using Wikis to Create Documentation. Intrigued, I dipped into the company‘s petty cash and ordered a copy.
When I got the book (booklet, actually; it runs 69 pages) … well, I wasn’t disappointed. It’s just that the booklet wasn’t what I was expecting.
If you’re looking for a step-by-step guide to using wikis to create and deliver documentation, Writing in the Open isn’t it. It is, though, an interesting and potentially useful set of best practices.
The bulk of the book
That’s devoted to organizing and presenting information. The first couple of chapters give a brief overview of:
- Choosing a wiki engine
- The pros and cons of using a wiki for documentation
- The basics of style and structure
- Collaboration and getting your community — internal and external — involved
- Migrating to a wiki
- Helping users adapt to using a wiki instead of a PDF or printed manual
Those topics, and a couple of others, are really only dealt with in a superficial manner. That lack of detail is apparent throughout the booklet. In fact, a lot of the information in the booklet isn’t anything new if you’ve been following the subject for any length of time.
Organization and navigation
This is the subject of chapter 4, and is probably one of the more useful parts of Writing in the Open. Unlike other chapters of this booklet, chapter 4 goes into some depth on how to organize and present information on a wiki.
It stresses the use and effectiveness of categorizing information using tags. Not just arbitrary keywords, but tags based on the type of information being presented — like tasks, product, release, and type of information. Doing this gives users a better sense of where they are, what documentation they’re looking at, and a better lay of the land. A good example of this in the wild is the documentation for the Fedora Project.
Chapter 4 also offers good advice on how to name pages and documents. Make those titles easy for humans to understand — for example, don’t call something xyz-user-guide; instead, call it User Guide for XYZ.
Another useful bit of advice is how to write for navigation. It’s more or less Technical Writing 101, but it’s a good refresher:
- Make text scannable
- Give precise locations for related information
- Clearly point to the next and previous topics
- Minimize the number of times that readers need to click to get to the information they need
Other information
The chapters on translation and visual design also present some useful guidelines. But, again, there’s not a whole lot new in those chapters for anyone with a few years of experience in our wacky profession.
The thrust of the chapter on visual design is that you need to develop standards for the use of icons and graphics, for captioning images, and the use of colour.
The translation chapter presents some points on writing for international audiences and working with translators. If you’re one of the many technical communicators who already do this — with a wiki or not — then you won’t find anything new here. For those who haven’t, it’s a good introduction.
Summing up
Writing in the Open is one of those could have been books. It could have been a lot more. It gives you enough information to whet your appetite, but you’ll quickly find yourself looking elsewhere for the same information. But in depth.
After receiving my copy of Writing in the Open, I had a short email conversation with Anne Gentle about the booklet. We agreed that the booklet would have been better if it was presented as a set of whitepapers or as a wiki on its own.
Maybe that way, Writing in the Open could have plumbed the depth of information that this topic really deserves.
Pingback: Tweets that mention A short review of Writing in the Open: Using Wikis to Create Documentation by Communications from DMN -- Topsy.com