Disclaimer: I am not involved in the proposal from Sandra (and others) which was the original post about.
Please note that it also is based on Diataxis. Additionally, it tries to target different personas (which is also a great idea in my point of view).. What I like about your approach, Martijn, is that its JS-Free and contains redirects for existing pages (which makes migration smooth). Additionally it uses a static page generator (I am no big fan of Jekyll, but you said, it’s only a prototype; there are other site generators in the Java world; but this is perhaps a minor issue). Perhaps you should join efforts? > On 27. Oct 2026, at 12:13, Martijn Dashorst <[email protected]> > wrote: > > 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 > >> -- Gerd Aschemann --- Veröffentlichen heißt Verändern (Carmen Thomas) +49/173/3264070 -- [email protected] -- http://www.aschemann.net
