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]

Reply via email to