maven-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Edwin Punzalan <epunza...@exist.com>
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:
> 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: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org


Mime
View raw message