Hi. Le dim. 19 janv. 2025 à 15:06, Gary Gregory <garydgreg...@gmail.com> a écrit : > > 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
It looks like a fine idea, best applicable to modularized components (where each "module" is strongly focussed). For example, much of what is in https://commons.apache.org/proper/commons-rng/userguide/rng.html#a2._Usage_overview and in https://commons.apache.org/proper/commons-rng/userguide/rng.html#a3._Library_layout could be moved to the respective "package-info.java" files of the concerned modules: https://commons.apache.org/proper/commons-rng/commons-rng-docs/apidocs/org/apache/commons/rng/simple/package-summary.html and https://commons.apache.org/proper/commons-rng/commons-rng-docs/apidocs/org/apache/commons/rng/core/package-summary.html In this instance we could still have a top-level userguide but it would mostly consist in a table-of-contents and links to the javadoc-generated files. > > This means writing documentation in Javadoc or Markdown which is now > supported by the JDK. We could still consider Piotr's proposal (a general move to "Asciidoc"): https://asciidoctor.org/news/2013/06/03/asciidoclet-announcement/ At first sight (for me), it definitely looks like a significant improvement in that we could eventually "normalize" the documentation style over all the components. [Something I had been wondering about for as long as I was here...] > 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. This still does not solve the issue of carrying documentation cruft that does not match what that version is actually doing. I suppose that we won't mandate that an older version's documentation should be corrected when something is found in it... Refactoring the documentation in such a way still seems to be a fairly simple (but time-consuming) task for a GSoC project. [To be conducted in some "experimental" branch of course, not "master".] Regards, Gilles >> [...] >>> [...] --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
