Awesome Sylwester! Thank you for doing all that work. Feels a more modern already.
I am still unsure where discussions about maven-site content changes - or the suggestion of changes - should take place. GitHub issues or threads on the mailing list? Would be nice if there is an agreement. > On 14. Nov 2026, at 19:36, Sylwester Lachiewicz <[email protected]> wrote: > > 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] >> >> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
