"Community" or "user" generated documentation?

Subject: "Community" or "user" generated documentation?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: "TECHWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Sun, 01 May 2005 08:40:54 -0400

Victoria Sharpe wondered: <<The product I am documenting already has some online community/user generated documentation, due to the previous poor customer service response and lack of detailed documentation.>>

A small political note: You may want to make such statements under an alias in future. You never know when an employer will
Google you to find out what you've been saying about them, and there have been several recent cases of dismissals and nasty lawsuits over what employees had to say about their employers in their private time.

<<At first I thought it would make my job easier, but I'm finding much of it to go against standard protocol for department inclusion in our official products.>>

It's not clear what you mean specifically about "inclusion". Don't forget that anything published online is copyrighted, and you cannot use it without permission. But that's not to say you can't use this material as a powerful source of inspiration. There's an anecdote I've never been able to pin down about an architect who created a university campus without any formal paths between buildings. When asked why, he replied that his goal was to let people wear their own paths in the grass, and by doing so, define where they (_not_ the architect) wanted or needed the paths to be.

The lesson of this anecdote is quite clear: by examining the paths your audience is creating online, you will gain key clues into the topics they consider to be of the highest priority and the approaches they find most effective in meeting their needs. If the organization or content of this information is subject to review and revision by the audience, as in the Wikipedia, you'll gain important insights into the form and structure of their "ideal" documentation. You'll also find much misinformation, disinformation, and myths or outright errors. Even the errors are important, because they tell you how people perceive the product--and thus what metaphors people use to understand the software, and what misperceptions you must correct.

All of this tells you how to create your own documentation: It sets your priorities, helps define your structure, and provides insights into the type of content you must create. Then you can create that yourself.

<<Speaking with other colleagues on a regular basis, I'd hear plenty of complaints about company executives not appreciating documentation efforts, so does this affect those efforts and if so, in what way?>>

This kind of resource is a two-edged sword. On the one hand, it clearly demonstrates to management that documentation is crucial, and that people will go to great lengths to get it. On the other hand, it clearly demonstrates that we're superfluous: fire us, and people will create their own documentation.

There's no easy way to balance these two problems, though you can certainly gather customer complaints and criticisms from the online forums, and with the writer's permission, quote the material to management to demonstrate a need for significant improvements in documentation. But managers are human too (rumors notwithstanding), and thus subject to Sturgeon's law: 90% of all managers make crappy decisions, either routinely or occasionally. (Sturgeon was more harsh, and was talking about writers.)

Allowing for the fact that Sturgeon was clearly being misanthropic, the fundamental point remains valid: managers are not always perfect, highly skilled, well-trained, always-logical beings, and often have other priorities, such as surviving the next budget cycle. Our concerns are not theirs, and may never even show up on their radar, no matter how well-justified our opinions.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


Accelerate the document lifecycle with full online discussions and unique feedback-management capabilities. Unlimited, efficient reviews for Word
and FrameMaker authors. Live, online demo:

You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.

Previous by Author: Re: Outsourcing of Technical Writers Employment
Next by Author: 40 buttons on one screen?
Previous by Thread: Re: Langevin Learning Services
Next by Thread: Re: watch your language! (or don't)

What this post helpful? Share it with friends and colleagues:

Sponsored Ads