> On Aug 9, 2020, at 8:49 PM, David Blevins <dblev...@tomitribe.com> wrote: > >> 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. >
I didn’t notice any differences between any of the doc versions in february except fairly different bad attempts to translate from markdown to asciidoc. IIRC some pages disappeared but I didn’t see any content updates in the versioned docs. I think it would be a really good idea for someone (hopefully someone more familiar with TomEE than me) to spend some time and organize the existing docs by hand. To me, the current “sort by tag” approach is an admission that the docs are incoherent and will stay that way. One way this might work would be to copy the “originals” from common to 7.0.x, then organize them there, and then propagate the organization to include stubs in the other versions, removing the copy from common. I suppose it might be possible to write a script to produce an include stub matching every “original” in all the copied versions, in which case we could start by moving the “originals” from common to 7.0.x. David Jencks > > > -David
