David Blevins and I had a long chat about the history of OpenEJB/TomEE documentation and I have a considerably different perspective now on the best way forward. I’d say the most fundamental shift is my realizing that even if doing everything with Antora is the most elegant and efficient solution, it may not be appropriate for TomEE because it involves extending the doc build system with javascript, whereas TomEE developers are more likely to be comfortable with java. Learning a new language in order to improve or even understand the doc build is too big a barrier. I’m likely to continue to see how, for instance, “marketing pages” and the tricks in the examples can be implemented in Antora, but because I want to learn how to do those things rather than because they are appropriate to use in TomEE.
I think the following steps make sense: - versioned doc consolidation: There are now 5 copies of the “tomee” versioned docs; one in common, and 4 identical copies done by asciidoc includes. Looking at one of these includes, it’s not very obvious how to edit the page, and certainly having one copy in ‘common’ is silly. So, the “originals” should be moved to one of the versions. The obvious choices are 7.0.x and 8.0.x. 7 might make it more obvious that changing the doc will change all 4 versions, but development is most convenient on master, 8.0. To make it easiest to locate the actual source, I’ll move the ‘original’ to 8.0. I hope that there will be a period of organization and improvement of the existing content followed by writing new content. After reorganization has settled down it may make sense to replace the “include” copies with one or two actual copies in the 7.0.x and 7.1.x branches so changes in master won’t inadvertently affect older versions. - common doc consolidation. The pages that show up in the common component come from two repos: tomee-site-generator and tomee-site. I don’t think it’s a good idea to have content in the same repo as site generator code, so I’m planning to move the content in tomee-site-generator to tomee-site. David said something indicating that this may not be an appropriate location, so perhaps a new repo would be appropriate…. I’ll investigate. Also, this content includes all the stuff that was previously in CMS and not served by the current site build. It’s apt to need a lot of editing, consolidation, etc, and it’s possible that this entire component should not be produced by Antora. However, at the moment, the only place all the content is accessible for consideration is in the Antora build, so I propose we leave it there for now, organize it, and consider what to do with it afterwards. One possibility, since Antora deals well with multiple versions, is to have something similar to the current common content minus the doc pages mentioned above as a “historical content” component version with the “current common” component version redirect to elsewhere. - examples. I’ve accumulated a pile of asciidoc fixes for the READMEs and I’ll see about getting them back to the master branch. - source directory structure. David pointed out that the shorter the path to the actual adoc files the more likely people are to find them…. I’ll see how much the path can be shortened. - publishing. It’s very tempting to work hard to create a highly unified site where the Antora and non-antora pieces are indistinguishable, however that may not be the best plan here. One of the persistent problems with documentation is that no one likes to work on it. Any complexity or difficulty is likely to deter people from contributing. A unified site would need a way for all the pieces of the site build to not step on each other, which could be hard to maintain. It may well be simpler to have two sites, one containing the front page, “marketing material”, possibly eventually the “common” component, the examples, and the other the Antora generated docs. This requires more investigation but the two-site approach is very attractive as reducing “friction”. Possibly this can lead quickly to actually getting the Antora portion of the site published soon. Thanks, David Jencks > On Aug 10, 2020, at 1:44 PM, David Jencks <david.a.jen...@gmail.com> wrote: > > The reason Antora has a separate front page is that Dan didn’t write > asciidoctor-openblock <https://gitlab.com/djencks/asciidoctor-openblock>. > Since I did, it’s easy to have a front page generated by Antora. He’s known > about this possibility for at least 5 years, but never found the time or > motivation to do it. > > If you have specific complaints about the front page I wrote, please air them > rather than ignoring my request for feedback. > > Could you be extremely specific about what you want generated by Antora and > what by tomee-site-generator and what by some other unnamed tool? Are there > parts of the current antora preview site that you think should not be > generated by Antora? (I expect to add examples to the preview shortly, but we > can discuss that separately). > > thanks > David Jencks > >> On Aug 10, 2020, at 1:09 PM, David Blevins <david.blev...@gmail.com >> <mailto:david.blev...@gmail.com>> wrote: >> >>> On Jul 14, 2020, at 7:34 PM, David Blevins <david.blev...@gmail.com >>> <mailto:david.blev...@gmail.com>> wrote: >>> >>> I think there are two gaps we need to understand to have a better >>> conversation about using Antora >>> >>> - Eliminating the Apache CMS from our lives. This is the biggest blocker >>> to any true progress. The only reason our site doesn't automatically >>> update now is because we're using the Apache CMS which has a manual publish >>> step that takes about an hour of machine time and periodic manual >>> checking/poking during that time. >>> >>> - Understanding `tomee-site-generator` isn't an enemy to Antora and doesn't >>> need to die or be eliminated. Among other things, we use it to generate >>> asciidoc content when and where we can. It will most likely need to run >>> just before Antora. Antora would be building some mix of manually created >>> docs and some generated docs. If Antora is not capable of committing >>> generated files to git, then `tomee-site-generator` is where we would do >>> that work. >>> >>> I recommend we first eliminate the Apache CMS so we have a hands-free >>> setup. Then I recommend we make it so the `tomee-site-generator` maven >>> project is the thing that kicks off and runs Antora. >> >> I've been doing some research and have some revised thoughts on how we could >> potentially proceed with this. >> >> Being terse as possible so we can try to get this out of discussion/debate >> mode and into action mode. >> >> Many Antora users, including Antora.org <http://antora.org/> itself, seem to >> use this pattern and I think it's probably the one we want. >> >> - https://antora.org/ <https://antora.org/> -> Built with a general >> purpose tool (Middleman+Asciidoc) >> - https://docs.antora.org/ <https://docs.antora.org/> -> Built with Antora >> >> - https://getfedora.org/ <https://getfedora.org/> -> Built with a >> general purpose tool >> - https://docs.fedoraproject.org/ <https://docs.fedoraproject.org/> -> >> Built with Antora >> >> - http://pinot.apache.org/ <http://pinot.apache.org/> -> Built with >> a general purpose tool >> - https://docs.pinot.apache.org/ <https://docs.pinot.apache.org/> -> Built >> with GitBook >> >> - https://www.mulesoft.com/ <https://www.mulesoft.com/> -> Built with >> a general purpose tool >> - https://docs.mulesoft.com/ <https://docs.mulesoft.com/> -> Built >> with Antora >> >> If we did this pattern we could probably get it done by end of week: >> >> - https://tomee.apache.org/ <https://tomee.apache.org/> -> Built with >> tomee-site-generator as is now >> - https://docs.tomee.apache.org/ <https://docs.tomee.apache.org/> -> Built >> with Antora >> >> We would request a new repo not connected to the CMS for >> docs.tomee.apache.org <http://docs.tomee.apache.org/> and have David push >> directly to it right now. David can lead that effort and just inform us on >> how it goes. >> >> We would then make the "Documentation" navigation item of tomee.apache.org >> <http://tomee.apache.org/> point to docs.tomee.apache.org >> <http://docs.tomee.apache.org/>. We'd still move it off the CMS, but I'm >> happy to do the lifting on that. >> >> I greatly prefer this approach to either 1) endlessly debating tools or 2) >> holding up David's work any longer. >> >> There would still be room for debate, but that debate could happen using the >> staging capabilities of the git-based solution. I think we'd be in an >> overall better position to introduce more changes with everyone on equal >> footing. >> >> >> Thoughts? >> >> >> -David >> >> >
