Wendy Smoak wrote:
On 10/31/06, Sebastien Arbogast <[EMAIL PROTECTED]> wrote:
Think of Hibernate or PHP documentation: one base reference book with
DYNAMIC comments in which people can share their thoughts and
experiences about each feature/chapter, remarks that can be later
integrated when the reference is rewritten. The problem is that,
whereas development itself is a highly-collaborative and efficient
process, nothing is really done so that documentation writing is
collaborative enough: no workflow, no direct input, no dynamic
comments, etc.
Many of the plugins have improved docs that haven't been published
yet. That's on my list for this weekend, determining whether it's
okay to publish them, or whether we need to establish a separate area
for the latest-and-greatest docs that may not match the released
version.
What I'd like to do for comments is make use of the MAVENUSER wiki
[1]. I'd like to see a link on every plugin site so that users can
share configuration examples or tell us that something is just plain
wrong.
What do you think? Any ideas on how to present that as an option?
What would the menu link be called? How should the pages on the wiki
be organized?
(The Better Builds book belongs to Mergere, so they would have to
agree to any changes in the way it is produced.)
[1] http://docs.codehaus.org/display/MAVENUSER/Home
I think the comments-based approach is the best option.
Users can post examples that work.
Authors can improve the documentation really easily, taking on board
comments.
An indication of the page's documentation quality would be the amount of
newby questions just asking what to do.
Gaps in the documentation would also be identified quickly by users.
I think it is by far the most agile approach to documentation.
Adam
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
