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
