Hi,
Some thoughts here, then going to follow with a mail that incorporates
some more of the past discussions, and hopefully, finally, an action plan.
John Casey wrote:
I've put my ideas here:
http://www.commonjava.org/~jdcasey/maven-documentation-proposal.html
Prefer this inline for a couple of reasons:
1) someone looking at the archives doesn't go to that 404 when you
delete it :)
2) easier to reply to. I'm just going to toss responses inline at the end.
1. We need to reorganize the website.
+1. I like the idea of guided trails (it's what I did on the m1 site,
and what I started on the m2 site at about alpha-1).
The big list of documentation has it's purpose, but it should be an
autogenerated index IMO. Same thing for search - it's a necessary tool
to have available, but not a substitute for navigation (I think everyone
is different in this case, so both need to be available and useful).
I think the docs for anything should be no more than 2 (or 3 in extreme
cases) clicks away by using the navigation. The home page should be the
descriptive version of the navigation, as well as having a general info
and some quick links.
We have two cases to consider: new users being able to progressively
learn Maven, and intermediate/experienced users who need to get back to
info they need a refresher on quickly, or new information for something
different they are doing.
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.
+1. Don't forget we have a couple of extra categories in user space (not
just users and developers). We have:
- people who need to build someone else's project with Maven. This is a
one page guide
- people who want to construct their own project's build with Maven (the
traditional 'user').
- people who write plugins (they may be users, or not)
- people who develop Maven (that'd be us).
We also need to consider people moving from Maven 1 or from Ant or
something else and help them along. I think again this is both an
individual guide and notes during the new users guide.
So, I think we have those 4 guides, plus the reference and cookbook +
general overview.
In the cookbook, I like the idea of having examples as archetypes
(Raphael suggested that in the thread, and I've done that recently for
Plexus - it's quite good. Maybe later we can even overlay it on a
project to merge into a POM and the rest of the tree :)
I think the cookbook is the best one to just suck straight out of the
wiki. I'll put my thoughts on this in the next mail, but I think we need
to resolve what we do with regards to the wiki vs APT.
2. We need to address the consistency of the site's navigation.
+1. The new site plugin has the ability to facilitate all this now.
Some other points from the URL you gave:
- how is advanced POM config different from advanced concepts?
- the dev guide should be a subsite generated from the main components
tree and includes information about the structure of the code, and
typical reports IMO
- Do you think the best practices is a separate guide? What might be
good is for each to be in the user's guide, and also be aggregated in a
single document (so this could just be a linked list)
- How does the cookbook compare to plugin use cases? I think we should
steer away from single plugin recipes (and instead link out to the
plugins from the cookbook - perhaps even aggregate the examples list).
The cookbook would just be non-plugin things (setting up a snapshot
repo), and multi-plugin things (using Java 5)
- in reference you say "project reports" - can you elaborate on which
you see going here?
- for the FAQ, can we have constraints on what goes into there? Does it
need to have sections or be multiple FAQs?
- in "site" you say "lose stock reports" - which ones?
Plugins...
1. We need to publish and validate against some sort of plugin
documentation
standards.
+1. Will discuss more below.
* POM Information - We need to have some basic organizational information
about the team that developed the plugin, along with the project
information
itself.
We should be explicit about the organizational info, etc, right?
- Contributors / Developers
+1, but for us I think it is fine to have one developer list in the top
level Maven POM (which we already have).
We need to be more diligent about contributors entries, and at some
point scrape them back out from the SCM logs ("Submitted by: ...")
- SCM URLs
- CI Information
Agreed, but the same for all in Maven (as its inherited), so nothing to
do here except add a check.
I'd add:
- Issue tracking URL (different for each)
- existence of plugin report (for generated doco)
- should we make prerequisite > maven mandatory?
So, how much of this does docck already validate?
* 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.
+1. There are more thoughts in an issue in JIRA about improving this too.
- Minimum set of generated reports like: javadoc, changelog, etc.
I'm not sure if we should have these in the plugin docs itself. These
two I'd agree with, but we also need a developer section just like the
main site.
* 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)
I think that it should be changed to index.html and we stop generating
that. The goal reference can be in a standard reference subsection.
- Usage (usage.html) - Outlines configuration for "normal" use cases.
Should also list recommended lifecycle phases.
I think these are a bit long right now, so I'd limit this to the very
basic standard use case. This will almost be boilerplate (just some
common configuration items, how to include it in the POM, and whether it
usually needs executions or not). It will probably repeat for each goal
available.
Consider this example:
- use case:
http://maven.apache.org/plugins/maven-release-plugin/introduction.html
- specific examples:
http://maven.apache.org/plugins/maven-release-plugin/howto.html (should
be broken out into examples/dryRun.apt, etc)
At the end of the usage page, I'd list each of the examples you mention:
- 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.
I don't think these should be directories. Most examples can be a 1
pager. So examples/usecase1.apt, examples/usecase2.apt, etc.
Examples are good, but let's keep that for complicated stories for now
(which are problem in the cookbook). We don't want to overreach here or
we'll just fall short.
BTW, I'm not against a subdirectory for a large example if that
eventuates, just saying we only go there if it gets too big.
- 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.
Can we integrate this into the docs instead? We need a way to
distinguish how versions behave without rewriting the docs every
release. We can achieve that with @since in the javadoc, but in the
general docs we should just add notes where something doesn't work in a
specific version. I still like having a FAQ for things that don't fit in
the flow for specific things, though, but don't know about "errata".
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.
I don't see how you can aggregate user's documentation, other than a set
of links like we have today (which is manual). Except for the addition
of this page:
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.
+1. We should hav eboth pages. In the notes you referred to "by tool
type" and "by project type". I don't think these are very helpful, I'd
stick to "category" (eg, J2EE - and they may have multiple), and
"lifecycle phase".
On lifecycle phases, I think plugins should have:
- default (currently annotated)
- recommended (not yet annotated - applies to both those with and
without a default)
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.
I think this should be in the main Maven site "plugin developers"
section. I'd also add plugin release instructions to the "maven
developers" section.
One more thing: you mentioned "upcoming releases" in the tree view. I
don't see how this is useful - what did you envisage?
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?
Yep, going to propose WAR, Deploy and Javadoc for starters.
I thought the jar plugin was one, but I can do some more research to find
out which plugins might be good candidates.
Probably a good one too.
Thanks,
Thank you!
- Brett
--
Brett Porter <[EMAIL PROTECTED]>
Apache Maven - http://maven.apache.org/
Better Builds with Maven - http://library.mergere.com/
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
