See comments inline...
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.
This is very important. Even though the look is consistent the feel is
not. Shared navigation and breadcrumbs will go a long way in getting the
user to remember the context in which the info is presented.
Plugin Documentation
================
1. We need to publish and validate against some sort of plugin
documentation
standards.
Yes! Having spent some time lately working on the M1 -> M2 POM converter
plugin I have spent quite some time navigating the sites of both Maven 1
and Maven 2 plugins.
The sites for M1 plugins are sooo consistent. There are always 3 entires
in the navbar: goals, properties and download. These can be paraphrased
into command line interface, configuration and changelog.
With M2 plugins it's a completely different story. Some plugins have
their goals on the starting page, others do not. It was only about a
week ago that I discovered the "Project Reports/Plugin documentation"
link in the navbar. It's hidden where I think nobody thinks to look.
For M2 configuration you're basically out of luck. Each mojo page does
have a list of properties, but these only cover the first level of
configuration. If a plugin has several levels it just doesn't show on
the site. Take the jar plugin as an example. The "archive" parameter is
a complex type, MavenArchiveConfiguration, which isn't documented.
Regarding what has changed for a plugin you have to hope that the plugin
author has included a changelog report. This report must be included as
standard.
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
Yes
* 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.
Yes
* 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.
Needs to be standardized, so the user knows where to look for specific
questions. The standard should also be documented so the user can go
there in case they are unsure of where to find something.
- 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.
Depending on the policy for deploying plugin sites, this might have to
go on the wiki. If you can't deploy a new site because the new site
includes documentation for features not yet 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
Thanks for raising this issue.
--
Dennis Lundberg
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
