It’s Not What You Say, But How You Say It

I haven’t gotten any user comments on the articles that have posted to the community wiki after blogging about it. But, just for argument’s sake, I do get comments from users just after I start together the review draft of the product documentation (which are based on the wiki articles). Do I incorporate the user comments as part of the product documentation as I would review feedback from the project team? Or should I just collect the user comments and have the product team review them for completeness and accuracy (as is done with bug reports)?

In other words, should a documentation wiki for an open source project be considered as complete and accurate when the product documentation is available separately? Or, more to the point, can a documentation wiki replace the need for separate product documentation?

My past experience working on open source documentation projects is that, while community wikis are a valuable opportunity to solicit feedback, they cannot replace the need for dedicated writers to create the required task, reference, and conceptual documentation. In other words, someone has to bake the cake before others can get a taste.

Perhaps the ideal role that community wikis and blogs can play will be to provide forums to discuss how to fill the gaps in the product documentation over the life of the product, perhaps starting with planning and deployment issues (at the beginning of the product lifecycle) to upgrade and migration issues (when the next product release is available).


Originally posted on by J. Aseo on 10/31/08.  You can find a summary of the effort needed to support the Project SocialSite community wiki (with an eye towards creating documentation for a future commercial release) on my wiki.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s