> On Aug 9, 2020, at 8:10 PM, Willes Reis <willesr...@gmail.com> wrote: > >> I’m not sure supplying identical copies of the documentation that claim >> to be for different versions is entirely desirable. Presumably we need two >> copies for javax/jakarta, but I’m not sure the one in tomee-site (from CMS) >> or the identical 7.0, 7.1, and 8.0 versions are truly essential. >> >> Next I may look into the examples. IIUC the java source for them is going >> to remain as javax for the foreseeable future. I think that means that the >> README’s should also remain javax-only. Among other things this should >> enable easy inclusion of source-code snippets and avoid confusion when the >> doc says jakarta and the source says javax. >> >> I suggested earlier that there’s no need for more than one version of the >> examples. I haven’t changed my mind on this and although someone didn’t >> seem to like the idea, I didn’t see any arguments why having more than one >> version was a good idea. Since IMO the largest problem with the docs site >> is that there’s too much outdated useless and wrong content, and it’s >> nearly totally disorganized, I think reducing the size will make everything >> else easier. >> > > I agree with David Jencks. > For sake of organization, I would like to suggest that we keep the > documentations isolated by branches, where each branch is a documentation > version (7.0.x, 7.1.x, 8.x and 9.x). Therefore, old docs will be > kept, while newly created ones evolve, beyond being compatible with > Antora's source repositories through branches.
I'd agree with that as well and it's what we currently have. I get the impression this is what David points out as a problem. We historically have had one base of documentation that applied to all versions. It's only been in the last year that we've attempted to branch the documentation as described. I'm the only one who put any effort into it, so it didn't go far. I do think that's the right long-term approach, but I am sympathetic to the argument with the documentation in the shape it's in we perhaps branched too early. I could be on board for focusing on one branch for a while with the plan to return to branching once we get something we like. As we have done one doc-base for all the versions over 19 of the last 20 years I wouldn't be willing to make that the permanent plan. A major problem with it is no one deletes anything because "maybe it applies to an older version." When Romain created the JBake setup he included only a subset of the documentation in an attempt to fix that problem. The way he did it ended up creating new problems as much of those documents still applied, but I understand what he was trying to solve. -David
