maven-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Edwin Punzalan <>
Subject Re: [Proposal] Documenting Maven
Date Fri, 16 Jun 2006 02:52:32 GMT

Definitely deserves +1

However, I'm still torn between using apt and a wiki site but whichever 
wins I think the obvious casualty will be the site-plugin.

If we continue on using the pages generated by the site plugin, and 
based from John Casey's "Core Documentation" point #2, it will be a 
major revision to the site plugin to pull that off.  But after that, 
things will be easier and the only problem I see will be the lack of 
contributions from outside the maven devs team bec, really, sending a 
patch for the first time is tedious.  Plus the fact that after sending 
the patch, one will wait for it to be patched and deployed.

Now if we work on a wiki site, then a lot of the information (javadoc, 
changelog, etc) already generated by the site plugin will be 
under-utilized (if not unused) and they will have to be reproduced in 
the wiki. Although, this may probably be another plugin's work but its a 
wiki, so there will probably be user edits on the same page and those 
edits should then be propagated back to the plugin's docs (again, 
probably another plugin's work).

Maybe there's a way to use both the wiki and the pages generated by the 
site plugin altogether for this?  So we can benefit from the pros of both.

Just my thoughts. 


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:
> 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:
For additional commands, e-mail:

View raw message