Apache

About this example

This is a proposal for maven.apache.org, not the official site. I made it, unasked, to show what the Maven documentation could look like with a different structure and one writing standard.

While redesigning the website of Apache Wicket, I saw the documentation effort on dev@maven and figured I could try for Maven what I did for Wicket: turn the existing documentation into tutorials, how-to guides, reference and explanation, following Diátaxis, and then find a structure for the whole site. Everything here is built from the sources of apache/maven-site.

Martijn Dashorst

What I changed

  • The structure. Five tabs, Docs, Downloads, News, Extend and Community, instead of one long menu, so users, plugin authors and contributors each have their own way in. Every page sits in a group of related pages, with previous and next.
  • A guide that follows one standard. 24 pages, each with one job: a tutorial, a how-to guide, a reference or an explanation. Every command on them was run on Maven 3.9.16, 3.10.0 and 4.0.0-rc-7. They replace the Maven pages they were written from.
  • A frame of its own. Maven navy and the feather’s orange, the Maven wordmark, and on every page the versions it holds for, and where to edit it or report a problem.
  • No JavaScript needed. Every page, menu and list works without it. JavaScript only makes the search answer as you type, and adds links on headings; without it, search opens a page listing every page.
  • Old addresses still work. The pages moved to the new structure, and every address maven.apache.org has published, 781 files and the anchors on them, still leads to its content: through a redirect, or for a page that was split up, through a page that says where each of its sections went. The build checks it.

What I left as it is

The other 150 or so pages are Maven’s own, carried over unchanged into the new structure: from pages written for Maven 2 to pages written for the Maven 4 betas, in as many voices. They say “Not yet checked against Maven 3.9, 3.10 and 4.0”, because they aren’t. They would need the same treatment as the guide pages. I changed Maven’s text in one place only, a published TODO; CONTENT-FIXES.md lists it.

What the standard looks like

Each kind of page does one job:

  • Tutorial: a lesson that builds something that works, step by step.
  • How-to guide: directions to reach one goal, for someone who already knows the basics.
  • Reference: the facts, complete and in a fixed order: elements, options, files.
  • Explanation: why Maven works the way it does.

Open an original next to what it became:

On maven.apache.org In this example What it shows
Maven in 5 Minutes Five tutorials on one project: create it, add a dependency, add a plugin, test and build, split into modules A tutorial builds one thing, step by step, that works at every step.
Guide to Using Toolchains An explanation, two how-to guides (another JDK, older Java) and a reference One page doing four jobs becomes four pages doing one each.
Working with Multiple Modules and its Maven 4 version An explanation, how-to guides to split a project, build part of it and share configuration, and a reference Two pages per Maven version become one set, with Maven 4 notes where 4 differs.
Password Encryption and Password Encryption (Maven 4) One how-to guide No separate page per version.
Using Mirrors for Repositories Use a repository manager as a mirror A how-to opens with when you need it, then gives the steps and how to check them.
Introduction to the Build Lifecycle Phases, goals and plugins An explanation says why, without steps in between.
Introduction to the Dependency Mechanism and Optional Dependencies and Dependency Exclusions An explanation, a reference of the scopes and how-to guides to trace a dependency, control its version, exclude it, use a BOM and make it optional Every claim was run on Maven 3.9, 3.10 and 4.0 before it was written down. facts/dependencies.md lists the 45 claims with their sources, the contradictions between the old pages, and what no page said.

The rules the guide pages follow, from front matter to how Maven 4 differences are marked, are in GUIDE.md. They could extend Maven’s own documentation style guide, which so far covers dates and POM indentation.

What turned up along the way

Running every command on three Maven versions turned up 48 places where Maven’s documentation and Maven’s behaviour disagree: outdated advice, examples that no longer work, and Maven 4 changes the pages don’t mention. They are on their own page, as a list to check.

How I made it

I built this with an AI assistant, Anthropic’s Claude, using the impeccable design skill for the structure and the front page. The guide pages were written from Maven’s own pages, and every command on them was run on the three Maven versions before it went in. Before building, the current site was reviewed against usability heuristics, the new navigation was tree-tested with 18 tasks, and the home page was put to a panel of reader personas; the testers and the personas were simulated by the AI, not real users.

This version of the example is built with Maven’s own tooling: mvn site, maven-site-plugin and Doxia, from the same sources as maven.apache.org. The frame is a skin of its own (doxia/skin), the structure is the site descriptor content/site.xml, one menu three levels deep, and every page is a source in content/. After the pages are rendered, four small classes run from the POM: Highlight colours the code, SearchIndex writes the search index, Addresses checks that every published address still works, and ThirdParty checks that no page loads anything from another host. Not in this version: the date a page last changed, which the version built with Jekyll shows.

Measured against the requirements

The Maven project collected what a new site has to do. This is how the example does it:

Requirement In this example
Content works without JavaScript Every page, menu and list. JavaScript only makes search answer as you type, adds links on headings, lists a plugin’s other versions, adds “On this page” on the plugin sites, and forwards a moved page straight to the right section.
Built with Maven, Doxia and the site plugin mvn site, with a skin and site.xml. The checks are Java classes run from the POM; nothing else is needed.
No published URL or anchor breaks, checked in CI src/published-addresses.txt lists the 781 addresses and 2,126 anchors of the current site; every mvn site, so every CI run, follows them through the .htaccess redirects and fails when one breaks.
Plugin and component sites get the new look The same skin builds the sites of the 37 active plugins that have a repository of their own, such as maven-compiler-plugin, at the release on maven.apache.org, with their goal pages and reports as they are. Under the header, each plugin has a bar of its own, with its name, version, what it does and its sections, and its home page opens with what to add to a POM. A plugin’s site.xml only names the skin; for all components at once, that is the site.xml of maven-parent. Five plugins were last released on a parent with the old site plugin, which cannot use a skin like this one; they are built with the site plugin of a newer parent.
An “edit this page” link on every page In the page facts, or in the footer of overview pages. A plugin’s pages are edited in the plugin’s repository; a goal page links to the code it is generated from.
Mobile layout and dark mode Every layout down to a phone’s width. Dark mode follows the system setting, without JavaScript.
No third-party requests None on the main site; every build checks it. On the plugin sites, one report loads images from another host: the Reproducible Central report of maven-artifact-plugin shows badges from shields.io.
Search, and moving between versions of a plugin’s documentation A search page that works without JavaScript and answers as you type with it. A plugin site links to its other versions in the archive; with JavaScript, as a list.
Sources stay close to the code The general documentation is in maven-site; a plugin’s documentation stays in its own repository, and the skin is an artifact that both use.

Not on the list, but checked as well: accessibility, against WCAG 2.2 AA. Every kind of page, of the main site and of the plugin site, in light and dark mode, passes the WCAG rules of axe-core 4.14, with one exception: the FAQ pages that Doxia’s FML module writes put an anchor directly inside a <dl>, which is for Doxia to fix. On the plugin sites, maven-plugin-tools turns a {@link} in maven-javadoc-plugin’s documentation into a link without text. In a browser I also checked that every link and field shows where the keyboard focus is, that no page scrolls sideways at 320 pixels wide, that wider tables and code scroll on their own and can be reached with the keyboard, that the WCAG text spacing cuts nothing off, and that search works with the keyboard alone.

What is still missing

  • The plugins that are part of a larger repository (Surefire and Failsafe, Enforcer, JXR, the plugin tools, Release, SCM, Wrapper), the Maven 4 betas of the plugins, and the other component sites (Resolver, Doxia, the reference documentation) are not built with the skin here; links to them lead to pages this example does not have.
  • A goal page does not name the class it documents, so its edit link goes to the plugin’s code rather than to the file; maven-plugin-report-plugin could print it.
  • The A–Z index and the list of every page on the search page are written by hand; the build should generate them.
  • The pages I left as they are have not been checked against the three Maven versions.
  • There is no single page yet on where Maven 4 stands and how to migrate.

Feedback

I’d like to hear what you think: in #maven on the ASF Slack.