maven-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Sebastien Brunot" <sbru...@ilog.fr>
Subject RE: Maven rant
Date Thu, 02 Nov 2006 10:59:26 GMT
Good ! When do you think it would be possible to have it online ?

Sebastien 

-----Original Message-----
From: Adam Hardy [mailto:adam.maven@cyberspaceroad.com] 
Sent: Thursday, November 02, 2006 11:44 AM
To: Maven Users List
Subject: Re: Maven rant

Wendy Smoak wrote:
> On 10/31/06, Sebastien Arbogast <sebastien.arbogast@gmail.com> 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: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: users-unsubscribe@maven.apache.org
For additional commands, e-mail: users-help@maven.apache.org


Mime
View raw message