Hi Matthias, hi all, You're right that the tooling question took over the thread. Here is where both stand now, and a proposal to move on to content and structure.
1. Tooling Fluido master (2.2.0-SNAPSHOT) has moved from Bootstrap 2.3.2 and jQuery to Bootstrap 5.3. The side menu is readable without JavaScript, link contrast reaches 4.5:1, the Google Analytics and Google Search options are gone, the theme switch only appears with darkThemeEnabled, and there is a migration guide ( https://www.google.com/url?q=http://migrate-2.2.md&source=gmail&ust=1794764432676000&sa=E). Rendered with it, maven-site passes its own axe check on all 300 pages with every rule switched on, and no published URL or anchor is lost. That covers requirements 1, 6 and 7 from my list, and requirement 4 once maven-parent picks up the new version. The next step is a release vote for Fluido 2.2.0. 2. Martijn's 48 discrepancies Thanks again to Martijn for running every command on 3.9.16, 3.10.0 and 4.0.0-rc-7. Status today: - 36 fixed in maven-site (the last ones in #1806, #1807 and #1814). - 5 fixed in plugin sources, live with the next releases: toolchains plugin (41), Surefire (42), Shade (44, 45, 46). - 5 were Maven or plugin behaviour, all fixed now: 24 (#13834, #13836), 35 (#13791), 43 (maven-surefire#3567), 11 (settings reference, plus #13835 and #13837 on master and 4.0.x), and 8 (fixed on maven-archetypes master; needs an archetypes release). - 10 is fixed on Central's side: its prefixes file now lists /archetype-catalog.xml (maven-resolver#2256). archetype:generate with 3.10.0 and an empty local repository no longer warns. - 36 needs no change (a log line differs between versions; no page claims either form). One open question, item 23: Maven 4 does not follow a Maven 3 master-password <relocation> in settings-security.xml. The encryption guide now says so. Is that intended? If not, I'll open an issue. 3. Content and structure I agree with you on the split between technical reference and user-oriented pages, and the four content types in the PoC's writing guide [1] give us a shared vocabulary for it. I would keep a single-page view as a possible output, not as the structure. My proposal: start with one slice in maven-site, "Getting started". Take the PoC pages and Martijn's rewritten guides as input, one PR per page, with redirects for any moved URL and every command checked on 3.9, 3.10 and 4. The navigation question (personas, or Björn's user guide / plugin development / internals) can be settled in a maven-site issue while that slice is written. Would you and Sandra be willing to lead it? Regards, Sylwester [1] https://www.google.com/url?q=https://github.com/support-and-care/doc-for-maven/blob/main/writing-guide.md%23the-four-content-types&source=gmail&ust=1794764432676000&sa=E On Mon, Nov 02, 2026 07:16 PM, Matthias Bünger via dev <[email protected]> wrote: > Hi Sylwester, hi others > > I think your summary covers important points mentioned about technology > or infrastructe requirements by the ASF. For me mainly the wish to stay > with Maven/JVM - and I agree that is has benefits, but also means that > we need to improve doxia/maven-site. > > What I miss - and which is/was a central aspect of the PoC (as Sandara > also stated) - is discussion about the content and its structure. An > aspect of the PoC is/was to have technical reference on the one side and > user oriented (also see [1]), with different personas in mind, on the > other side. All people on the thread who have written something about > this topic agreed that it needs improvement, but I don't see any > ideas/suggestions about the "how", except Ondrej's point to also add an > ADHD persona. > > About structre: Delany suggest to have a single page documentation. I > personally don't think that this fits together with the idea to have > technical reference and user guides esp. for a large tool/ecosystem like > Maven. > > I would with to see more context on strcture/content. But I have the bad > feeling that the thread got "hijacked" by a clash-of-tooling - tbh a > common thing when developers discuss ;) > > Have a good evening > > Matthias > > [1] > https://github.com/support-and-care/doc-for-maven/blob/main/writing-guide.md#the-four-content-types > > > Am 29.10.2026 um 19:55 schrieb Sylwester Lachiewicz: > > Hi, > > > > Thanks to Sandra and Martijn for the two examples, and to everyone for > the > > feedback. Before we pick a design or a tool, I tried to collect the > > requirements that came up in this thread, so we can measure every > proposal > > against the same list: > > > > 1. Content works without JavaScript; search or a theme switch may use it > as > > an extra. > > 2. The site keeps being built with Maven, Doxia and the site plugin (or > at > > least a JVM toolchain), as Elliotte and Manfred asked. But still open to > > alternatives that help contribute to site content. > > 3. No published URL or anchor breaks: moved pages get redirects, ideally > > checked in CI. > > 4. Plugin and component sites get the new look too, and keep their > uniform > > structure (goal pages, parameters, reports). > > 5. An "edit this page" link on every page. > > 6. Mobile layout and dark mode. > > 7. No third-party requests (fonts, analytics), in line with the ASF > privacy > > policy. Embedded in site (as now) is ok. > > 8. Search, and a way to move between versions of a plugin's > documentation. > > 9. Sources stay close to the code they document. > > > > Items 3 and 4 are, in my view, the ones the current proposals do not > cover > > yet. > > > > What is missing from this list, or should not be on it? I would like to > > keep the discussion open, and track the outcome in the maven-site > > repository so it stays visible to everyone. > > > > Regards, > > Sylwester > > > > On Thu, Oct 29, 2026 12:46 PM, "mfriedenhagen.gmx.de via users" < > > [email protected]> wrote: > > > >> Hi, > >> > >> I for one like Martijn's design. I disagree that only people already > >> convinced of Maven should be addressed. > >> > >> Personally I dislike documentation pages which do not tell people what > the > >> software is good for and why I should use or try it. > >> > >> Besides the start page, the rest is easier to access for first-time > users. > >> > >> Additional benefit: it is usable on mobile phones as well and the search > >> works quite well for those knowing what to look for. > >> > >> Mit freundlichen Grüßen > >> Mirko Friedenhagen > >> -- > >> > >> > >> Am 28.10.26 um 12:26 schrieb Elliotte Rusty Harold > >> > >>> First impression: this feels like a marketing page, not developer > >>> documentation. The target audience for the maven site are developers > >>> who want to use Maven. The purpose is not to sell Maven to an > >>> undecided audience. > >>> > >>> On Tue, Oct 27, 2026 at 10:56 PM Martijn Dashorst > >>> <[email protected]> wrote: > >>>> On Tue, Oct 27, 2026 at 7:59 PM Manfred Moser < > [email protected] > >>>> wrote: > >>>> > >>>>> Totally agree with Elliotte. We should us our own tooling or at a > >>>>> minimum stay with Java/JVM-based solution to keep things simpler. > >>>>> > >>>>> The docs source should also continue to sit with the same repos as > >> they > >>>>> are so we dont have to change a lot of infra and process. > >>>>> > >>>> I agree, especially since all the plugins also use doxia (if I > >> understand > >>>> it correctly). > >>>> > >>>> I don't think using doxia is a detractor for good documentation, nor a > >>>> modern web > >>>> design. But it might need some tweaking to enable new features, but I > >> think > >>>> that is > >>>> for the better. > >>>> > >>>> I rebuilt my demo site using doxia, a new skin and a search index > >> update > >>>> all from > >>>> maven. This version of the example is built with Maven’s own tooling: > >> mvn > >>>> site, > >>>> maven-site-plugin and Doxia, from the same sources as > maven.apache.org. > >> The > >>>> frame is a skin of its own (doxia/skin), the structure is the site > >>>> descriptor content/site.xml, > >>>> one menu three levels deep, and the landing pages, the news and the > A–Z > >>>> index are > >>>> Markdown pages written from the same data by a small script. After the > >>>> pages are > >>>> rendered, two small classes run from the POM colour the code > >> (Highlight) > >>>> and write > >>>> the search index (SearchIndex). Not in this version: the date a page > >> last > >>>> changed; > >>>> moving pages to new addresses would add .htaccess redirects. The > >> version > >>>> built > >>>> with Jekyll has those. > >>>> > >>>> You can see the results here: > >>>> > >>>> https://dashorst.github.io/maven-site/mvn-site/ > >>>> > >>>> Let me know if you have any feedback. > >>>> > >>>> Kind regards, > >>>> > >>>> Martijn Dashorst > >>> > >>> > >>> -- > >>> Elliotte Rusty Harold > >>> [email protected] > >>> > >>> --------------------------------------------------------------------- > >>> To unsubscribe, e-mail: [email protected] > >>> For additional commands, e-mail: [email protected] > >>> > >>> > >> > >> --------------------------------------------------------------------- > >> To unsubscribe, e-mail: [email protected] > >> For additional commands, e-mail: [email protected] > >> > >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [email protected] > For additional commands, e-mail: [email protected] > >
