On Sun, 19 Jan 2025 at 13: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.
Antora appears to be a way to create a website from lots of Asciidoc sources. The maven-site-plugin has a similar focus, but supports several document sources including Asciidoc and Markdown. The site plugin also has a tight binding with the report plugin, which is used to generate reports such as JavaDoc, Changes, Japicmp etc. The site plugin also supports generation of pages for mailing lists, issue management, dependencies etc. I don't think these are directly supported by Antora, and I think at least some of the reports are essential for utility libraries such as Commons. Antora looks to be powerful and easy to use, but would probably require extra work to add the extra reports we need. > > > > 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 > --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
