Revdocs on a wiki

[Dan Shafer]

Tim.....

I've kept my counsel as this thread unwound, determined not to become  
embroiled in yet another discussion about the Rev docs, which remain  
among the best of any software development tool I've seen. But your  
post dragged me out of the bushes. While I agree with much of what  
you say, your below comment is one I couldn't let just slip by  
without comment. :-)

On Oct 27, 2005, at 4:12 PM, Timothy Miller wrote:

> users, given the opportunity, could always improve whatever the  
> engineering and technical writing staff came up with, with no  
> publication delay.

<rant>
I wonder why it is that everyone thinks s/he can write better  
documentation than the professionals but scarcely anyone thinks they  
can write better software than the engineering team. Writing good  
docs is a skill that takes years to develop. The tech writer must be  
part engineer, part programmer, part writer, part user. I know most  
people don't realize how much software QA and debugging is done by  
the doc staff at major tech companies, but I can assure you it's a  
huge contributor. In trying to describe how something works or when  
to use some feature, the writer has to stand in for the uneducated  
user and try things that the engineers never thought a user would do.  
So while it is absolutely true that users can add a great deal to the  
information base from which a tech writer works and while it's  
certainly often true that end users could suggest things the tech  
writer didn't think about, the idea that users should be allowed to  
*edit* (as opposed to comment on) documentation makes as little sense  
to me as the idea of allowing the engineers at customers' companies  
to edit the source code of the product.
</rant>

Several years ago, I headed up a project which involved an extensive  
documentation effort and this same issue was raised. I like the way  
we solved it. Furthermore, I happen to have access to the tool and a  
server where it could be deployed and would make both freely  
available if: (a) at least one or two others would be willing to  
share site management and editing chores; and (b) the community  
thinks it's a good idea. The approach we used was akin to a  
discussion board. Each section of the docs was a topic on the board.  
Everyone who was a member (and that term could be loosely defined, of  
course) could add their comments to a section of the docs. There was  
also a general topic area where people could post questions and  
suggestions about the docs in their totality. Periodically, an editor  
assigned to a given section would go through the comments,  
incorporate the suggestions that made sense, edit the topic, create a  
new topic on that section, hibernate the old, and move comments that  
remained relevant to the new topic area.

At the same time there was a way for any interested party to: (a) see  
the docs without the comments; (b) navigate using only the "official"  
docs; and (c) view and print (and save as PDF) all or some of the  
currently official documentation. This model is called "managed open  
collaboration" and I think it presents the best of all possible  
worlds in terms of encouraging and incorporating useful input without  
disrupting the accuracy or utility of the original and modified  
documentation.

FWIW.




~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Dan Shafer, Information Product Consultant and Author
http://www.shafermedia.com
Get my book, "Revolution: Software at the Speed of Thought"
 From http://www.shafermediastore.com/tech_main.html