Hi all, I don't think we need a site beyond a "simple" Maven site, let me explain...
I like what projects like Juneau did which is to put all the documentation in Javadoc. When you go to https://juneau.apache.org/ and click "Documenation", you go to https://juneau.apache.org/site/apidocs-9.0.1/index.html and you get the full user manual and Javadoc. We do this in Commons with BeanUtils: https://commons.apache.org/proper/commons-beanutils/apidocs/org/apache/commons/beanutils2/package-summary.html The advantage is simple (to me): You get the documentation for the version you care about, especially if you look at the Javadoc for an older version (using javadoc.io or our own archives). See also the PostgreSQL docs for the same idea but not in the Java world: https://www.postgresql.org/docs/current/index.html This means writing documentation in Javadoc or Markdown which is now supported by the JDK. And yes it's ok to use moder Java to build components that target older byte code. I'd also like our Commons sites to be something like our BeanUtils site with a menu somewhere that points to the Javadoc for each version (alievating the need to rely on javadoc.io). This avoids the need for a User Manual link and pages on the site which will not match old versions. I also am not a fan of docs that are have version tags all over the place with "this was added in version foo", just show me what I care about. Many pennies, Gary On Sun, Jan 19, 2025, 08:22 Gilles Sadowski <gillese...@gmail.com> wrote: > Hi. > > Le sam. 18 janv. 2025 à 19:14, Piotr P. Karwasz > <pi...@mailing.copernik.eu> a écrit : > > > > Hi Gilles, > > > > On 18.01.2025 18:09, Gilles Sadowski wrote: > > > Yes, it's likely a lot of work. > > > Maybe a GSoC project (for which the candidate should somehow > > > demonstrate the capacity to achieve the result _before_ being > > > accepted, so that we don't end up doing twice as much work...)? > > > > The changes in `logging.apache.org` took close to 1000 work hours (2 > > developers for 3 months) and were financed by the Sovereign Tech Fund > > (now Agency). Commons has also several critical projects, so we could > > apply for one of its programs. > > It's clear what "Log4J" does; I'm pretty sure that there won't be > a consensus here about what the scope of "Commons" is. My > impression is that it would be difficult to explain what the funding > will be used for. > E.g. they may not be interested in rarely used components; > but does that make them less "critical"? > A slick website is "nice" but not really "critical" (as long as it is > not tampered with). > Of course, I'm certainly not opposed to someone trying to get > resources to do <something>. > > > > > How much time would Commons take, depends on what we want to do: > > > > 1. Moving from SVN to Git should be easy. > > > > 2. Converting from a variety of formats to Asciidoc can also be done > > almost automatically. > > I was going to ask "why Asciidoc", but most of the answers is there > https://asciidoc.org/#about > > A primary question is then: Do we want to normalize the "Commons" > documentation so that all components use "Asciidoc"? > > > > > 3. Replacing `maven-site-plugin` with Antora can reuse the work done in > > Log4j. > > I don't know what "Antora" is. But if "Log4J" did the work already and > people are happy with the result, it's a strong incentive to indeed follow > that path. > > > > > 4. Proofreading and expanding the documentation is the part that really > > takes time. > > I guess that in "Commons" it would strongly depend on the component. > Some are in pretty good shape thanks to a lot of time having been put > into it and/or the scope is very focussed. Others contain a lot of code > that is (probably) rarely used so that issues could go unseen for a long > time... > > Anyways, your points 1, 2, 3 seem a good plan for a GSoC project. > Now would be the time to define such a project: > https://community.apache.org/gsoc/ > > Regards, > Gilles > > > > > Note: after the refactoring of the Log4j website we noticed a lot of > > issue reports against documentation. It is probably a good sign: it mean > > people actually read the docs. > > > > Piotr > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > >
