Brett, I appreciate the concern on the subject. My main concern is not thorough documentation - it's basic "what is this and what is it for" doucmentation. Adding goals to a plugin but not including basic user documentation just perpetrates Maven's reputation as a poorly documented project. There needs to be a basic quality level for documentation which is enforced. In the case of plugins, I consider the minimum to be common examples and usecases for the goals within the plugin. A plugin and its goals are useless if a user cannot determine how to use them to solve his problems.
I've seen some amazing progress on testing in the last few weeks. Perhaps a similar effort in the next two months around documentation would lead to similar results. At any rate, I think releasing the plugins ASAP is important. I can't spend a lot of time on the bleeding SVN edge but once they are released I can start contributing to the documentation myself. -----Original Message----- From: Brett Porter [mailto:[EMAIL PROTECTED] Sent: Monday, May 08, 2006 6:43 PM To: Maven Developers List Subject: re: plugin docs was: [vote] Release maven-assembly-plugin 2.1 Mike Perham wrote: > -1 due to missing documentation. > > John, I built the site but I don't see any documentation on the new > features and how to use them. Did I just miss something? No, they weren't updated by those contributing patches. This mostly occurred before we had our previous discussion about whether to accept patches without docs. > Some sample > usecases would be helpful for people trying to understand when you use > one goal versus another. The "examples" link is an great example of > usecase documentation. Also the "Descriptor Format" link in the site > left menu gives me a 404. You need to run modello:xdoc to get those. I thought it was wired in though. I'm trying to think what the best option is here at the moment. I certainly understand the need to catch up in the docs, but on the other hand we have users begging for us to release features that are already complete in SVN/patched in JIRA/etc. I have a queue of 14 plugins to release here with all the bugs and patches cleared out. I also know that several of us are away for two weeks due to JavaOne, so when you factor in time to work on the docs, we're looking at 4-8 weeks to get all these plugins out. We should never have gotten into this situation, but I think the best balance is: 1) do as much doc as is practically possible before the release 2) release as is to satisfy users demanding the fixes/features and to reduce load on the users list (many faqs are addressed by things like a javadoc and site release) 3) no more releases until the docs are in shape. I also think that we need a better way to make the plugin docs accessible. I'm concerned that an effort here right now is a bit wasted as they are really hard to find. What do others think? - Brett --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
