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, when it changed, 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; without it, search opens a page listing every page.
- Old addresses still work. All 310 old URLs redirect to the new place of their page.
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. |
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.
The example is built with Jekyll, because that was quickest for a demonstration. Maven would not need Jekyll: the frame could be a skin for maven-site-plugin, the structure a site descriptor, and the lists and the search index a small Doxia macro module. The same site built by mvn site shows that it works: a skin of its own, one menu in site.xml, and the code coloured and the search index written after the pages are rendered. Every component site, from the plugins to the reference documentation, would get the same look with the same skin, and the old addresses could move as 301 redirects in the .htaccess files maven-site already uses.
What is still missing
- The plugin sites and the reference documentation are not part of this build, so links to them still lead to the current design.
- 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.