Than you Sandra for proposal. Can we open and discuss proposals on maven-site and not outside repo that users my not see/be aware?
Sylwester wt., 27 paź 2026, 18:01 użytkownik Sandra Parsick <[email protected]> napisał: > 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] > >
