Hi John,
Here are inlined some propositions.
2006/6/15, John Casey <[EMAIL PROTECTED]>:
Hi everyone,
[SNIP]
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
================
There are already some ideas to pick in the mavenuser wiki
[SNIP]
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:
Here i would say that the examples should be archetypes...
[SNIP]
Almost +1 for all, here are the links of started documentation that could be
merged (with the authors agreement) :
http://cvs.peopleware.be/training/maven/maven2/index.html
http://docs.codehaus.org/display/MAVENUSER/The+Maven+2+tutorial
http://docs.codehaus.org/display/MAVENUSER/Proposed+Documentation
Hope this helps.
Raphaël
