On Mon, 26 Oct 2026 at 20:54, mwood.iu.edu via users <[email protected]> wrote:
> On Sat, Oct 24, 2026 at 11:44:08AM +0000, Björn Raupach wrote: > > Documentation is all about content and structure. > > > > The official Maven documentation at https://maven.apache.org/ has lots > of great content but it lacks structure. It is hard to navigate. There are > so many topics thrown at you, which most of the average users don’t need or > care about. It is written by technical people for technical people. User > guides, plugins development and Maven internals are not well separated from > each others. Should be. Make it much more readable. > > Seconded. > > One thing I've found to work well is to consider separate views of the > product for different needs. In ye olden days both DEC and IBM (and > likely others) would issue two manuals for a product: a Reference and > a User's Guide. The Reference is for when "I want to see everything > the product does, feature by feature, because I'm looking for complete > information on something specific" and the Guide is for when "I want > to know good ways of thinking about the product as I apply it to my > task." > > In my own work on documentation (elsewhere) I've found that > disentangling reference and advice makes documentation clearer and > more easily navigable. Diátaxis takes the same idea further: four kinds of pages, tutorials, how-to guides, reference and explanation, each doing one job. I used it to split the Wicket user guide, until then a single HTML page or a 330-page PDF, into 130 pages: https://wicket.apache.org/docs I've tried the same for Maven, using some spare AI tokens at the end of the week to build an example of what the Maven site could look like. I kept Maven's own content and mostly changed where it lives and how you find it. The 24 new guide pages follow one standard, and every command on them was run on 3.9.16, 3.10.0 and 4.0.0-rc-7; the other ~150 pages are Maven's existing content as-is, from Maven 2 to 4, and would need the same treatment. The site works without JavaScript and old URLs redirect. It's built with Jekyll for the demo, but the same could be done as a skin for maven-site-plugin. The look stays close to what you know: plain and quiet, with Maven's logo and Maven's own navy instead of Bootstrap 2's blue. The example: https://dashorst.github.io/maven-site What I changed and how I made it: https://dashorst.github.io/maven-site/about-this-example.html It's a proposal, not something the Maven project has agreed to. I'd like to hear whether you find things faster in it than on maven.apache.org. Try something you looked up recently, like building a single module or setting up a mirror, and tell me where you got stuck or what you couldn't find. A fellow Apache enthusiast and Maven user Martijn Dashorst >
