Rahul, I agree that the accompanying projects/sub-projects should be documented but that also seems like common sense. I also agree heavily with Jimisola. When I first tried Maven, I canned it within a mont or so due to lack of documentation. That is getting better with "Better Builds With Maven" and updated documentation of some of the plugins but I do also think it could be better. For example, if every Maven plugin could be as documented as the Jetty6 plugin, that would be a welcome addition. If you go to most of the included maven plugins, most have information outlining the configuration elements but no real documentation as to what they mean, usage scenarios and examples. I know this isn't the case with all plugins but take the maven-archetype-plugin for example. You don't even know which archetypes are available and what they do. To figure that out, I had to checkout the maven repository for availabilities. I can attest to the bad taste that Maven leaves in your mouth and I do agree that for most, it is an obstacle. I also think that it wouldn't be a huge undertaking for each plugin to be documented properly. It is almost becoming a necessity.
Take care, Jeremy P.S. - I have already given a +1. ;) On 6/14/06, Rinku <[EMAIL PROTECTED]> wrote:
+1 for documentation reorganization on the Maven website. Also, quickly wanted to add that documenting Maven would, IMHO, encompass a number of other projects/sub-projects (For instance ones appearing in the top navigation on the Maven homepage). I think we need to include them in the scope as well. Thoughts? Cheers, Rahul John Casey wrote: > Hi everyone, > > I know we've talked about this quite a bit already. Actually, I'm having > trouble finding the past threads on this topic in my email...can > someone who > knows please link them in? > > Basically, I've talked to Brett, Jason, and a few other Maven developers, > and I think it's time we started making website documentation a top > priority > for Maven. I doubt anyone will argue on that point, but what we really > need > to agree on is what to document (priorities), and how to represent it > on the > site (layout). I've been working on a proposal today, which would give my > thoughts on both the layout and the content. It's mostly just a large > outline; some of it represents a potential Table of Contents or something > similar for the website, and some of it represents the types of > documentation and particular qualities I think we need to address. > > > > I've put my ideas here: > http://www.commonjava.org/~jdcasey/maven-documentation-proposal.html > > > > I apologize if it looks like I ripped off someone else's ideas...I > honestly > cannot find those old email threads, and I'm not entirely sure how > closely > this will track against the emergent consensus. > > I've separated the list into two broad categories: Core Documentation and > Plugin Documentation. First, I'd like to summarize the core side, then > I'll > talk briefly about the plugins side. > > Core Documentation > ================ > > 1. We need to reorganize the website. > > For anyone who has spent any time supporting Maven, it's obvious that > what > information we do have on the website is nearly impossible to navigate. > After looking at some other project websites, and remembering what I find > that works well, I think it might be a good idea to represent the > website as > a set of manuals. Each manual would be linked using a top-level menu > item, > and would have a strong organization (Table of Contents) within. This > concept is somewhat loosely applied in the list of items, which has > headings > like Overview Material, User's Guide, Getting Involved (which contains > the > Developer's Guide), Cookbook, Reference, etc. I'll let you all take a > look > at those collapsing lists for more detail. > > 2. We need to address the consistency of the site's navigation. > > The site feels like a bunch of nested websites that just happen to share > the same logo and CSS. In many cases, traversing a level or two down > results > in a completely new set of navigational elements on the left! I think we > need to make that left navigation consistent, and provide some sort of > breadcrumb functionality to help give the current page context. Whether > these breadcrumbs are in the form of a list at the top, or a folder > analogy > in the left navigation, or something else, is another question. > > > Plugin Documentation > ================ > > 1. We need to publish and validate against some sort of plugin > documentation > standards. > > Plugins all need to provide some of the same basic elements of > information > in order to be usable. It's even simpler if these elements are > consistently > named across the set of plugins we index, since the user will always know > what sorts of things to expect when he clicks on Overview. I think we > should > publish some sort of standard that addresses minimal information > requirements in the following areas: > > * POM Information - We need to have some basic organizational > information > about the team that developed the plugin, along with the project > information > itself. > > - Contributors / Developers > - SCM URLs > - CI Information > > * Generated Plugin Documentation - This is derived from the annotations > given to designate the different parts of a plugin, and should be > adequate > as "quick reference" information. > > - Mojo-level descriptions provided in the class-level javadoc of all > mojo classes > - Parameter-level descriptions provided in the field-level javadoc of > all mojo parameters - NOTE that @readonly and @component should be > suppressed from generated docs. > - Minimum set of generated reports like: javadoc, changelog, etc. > > * Authored Documentation - This will be a set of documents in > src/site/** > which will give the user enough information to use the plugin > effectively. > It should include at minimum: > > - Overview (overview.html) - What does the plugin do? What are its > features? (NOTE: could be changed to index.html...not sure) > - Usage (usage.html) - Outlines configuration for "normal" use cases. > - Examples (examples/**) - Provides a set of single-scenario > documents > that perform the following functions: > > 1. Provide a context for the plugin's usage - what problem > are we > trying to solve? > 2. Follow a real-world example from start to finish - Not an > abstract, disconnected set of imaginary configuration examples > 3. Provides downloadable sample code (this one might be too > much, > I dunno) > 4. All directories under examples/** should contain > index.htmlfiles which serve as a Table of Contents for that > subsection. > > - Errata (errata.html) - Documents TODOs and GOTCHAs for the current > release. This is meant to address workarounds for problems whose fixes > haven't yet been released. > > > 2. We need to provide some aggregated documentation about the plugins we > index. > > Mainly, this would consist of two main sections: User's > documentation, and > Developer's Documentation - both at the aggregate level. > > For users, we'd categorize the plugins in a couple of different ways, > possibly starting by listing them by lifecycle binding and by major > category > of problem the plugin addresses. > > For developers, we'd provide a HOW-TO document that explains the > documentation standards for a plugin, and suggests methods for > streamlining > and maintaining the plugin documentation. Additionally, we should > provide a > plugin which will help them validate plugin documentation against the > published standard. > > > 3. Finally, I think we need to have some prototypes for this process, > where > we can roll them out early and get some feedback. We have a few plugins > which are almost ready for release, I think...maybe we can start with > those? > I thought the jar plugin was one, but I can do some more research to find > out which plugins might be good candidates. > > > > Sorry this email is so long-winded, but I think we'd all agree that > there is > a lot to get done. Hopefully, this document will serve as a decent > starting > point for discussion. I'd like to drive this to consensus soon, so we can > get started. > > Thanks, > > John > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
