In our PoC, we are also using a static page generator. In our case it is
Zensical [1]. We write an ADR [2], where we described why we choose it
and which other option we had. There are so many static site generators
in the world, that of course we have to reduce the selection to some of
them.
[1] https://zensical.org/docs/get-started/
[2]
https://github.com/support-and-care/maven-support-and-care/blob/main/src/docs/ADRs/ADR-001-documentation-site-generator.md
Am 27.10.26 um 13:08 schrieb Gerd Aschemann:
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
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
