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]
