John, I'll put a +1 on that one. I am fairly new to Maven development and non-standard Maven use and I feel that the documentation is lacking. Even when there is documentation it isn't complete.
Take care, Jeremy On 6/14/06, John Casey <[EMAIL PROTECTED]> 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
