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
_______________________________________________
use-revolution mailing list
use-revolution@lists.runrev.com
Please visit this url to subscribe, unsubscribe and manage your subscription
preferences:
http://lists.runrev.com/mailman/listinfo/use-revolution
