Preview at https://tomee-preview.s3-us-west-2.amazonaws.com/index.html <https://tomee-preview.s3-us-west-2.amazonaws.com/index.html>
Current state: - all content from old source locations on the site (AFAICT, I’ve stopped looking). This includes all the .md and .mdtext from tomee-site. - no asciidoc syntax errors - no internal broken links - (easy) content deduplication There are still some content fixes left to do such as swizzle elimination. I don’t think these are currently any worse on the preview than on the live site. I think the main remaining questions about the website organization relate to duplicate and useless or obsolete content. To me, history makes clear that maintaining the website is difficult for the community and generally neglected. I think the highest priority should be making it smaller and better organized so there’s less to maintain and when someone has an interest in working on it it’s not an insuperable task to figure out how. The current preview organization has: - content from tomee-site-generator and tomee-site under “common”; there’s only one version - content from tomee branches under “tomee” with three versions. Almost all of this content also appears in “common”; see (1) - content from the tomee master examples under “examples”, with 3 language versions. - the beginnings of embedded JavaDoc, see https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/tomee/index.html <https://tomee-preview.s3-us-west-2.amazonaws.com/tomee/8.0/tomee/index.html> I think the largest remaining questions about the website organization relate to duplicate and useless or obsolete content. To me, history makes clear that maintaining the website is difficult for the community and generally neglected. I think the highest priority should be making it smaller and better organized so there’s less to maintain and when someone has an interest in working on it it’s not an insuperable task to figure out how. 1. Previously, except for perhaps a couple of pages, the 8.0, 7.1, and 7.0 doc branches were identical except for different asciidoc syntax errors. Now that I’ve brought in the previous .mdtext content from tomee-site git repo and fixed the syntax errors, there are 4 identical copies. I’ve made this obvious by eliminating the full text of all but one and using include:: directives in the other 3. I think much of this content is somewhere between outdated and wrong, so having 4 identical copies seems like a less than ideal situation. I think it’s extremely unlikely any of this content is going to change, although some might be removed. I’d suggest keeping only the copy in “common” and leaving the versioned branches for release-specific content, with a pointer to the common docs. 2. I haven’t examined the situation in detail, but I think that the examples are pretty much the same for 7, 7.1, and 8. I don’t think old examples will ever change, but new ones added. Therefore I suggest having only one “examples” component with each example saying “since version xxx”. 3. There are a lot of pages that are basically empty. Maybe someone had an idea that documenting something would be a good idea and added an empty page for it. Since these have been around for many years with no change, I think it’s time to remove these. 4. There are a lot of pages explaining svn, tomcat <= 6, OpenEJB 1 and 3, etc. Is there any reason to keep these? 5. There are several pages with helpful links to peoples people.apache.org accounts. This is surely not appropriate, and I think all of these are seriously out of date. Is there any reason to keep these? ——————— JavaDoc I’ve experimented with javadoc a bit. In my tomee-site antora branch there’s a small example of using maven to build a java 11 style javadoc jar from a few bits of stuff pulled into the jbake-built javadoc. This makes more sense to me than running the javadoc tool every time you want to preview the website. I also have an experimental Antora plugin that adds the javadoc to the generated website. There are several ways to do this, but I like the idea of having the javadoc content inside the Antora page layout: this is what the preview has. I’m having trouble figuring out how to make the antora navigation and javadoc search work in this context. Also, javadoc jars now include some gpl2 licensed scripts, so I’m a bit unclear as to whether it’s even in line with Apache policy to show generated javadoc on an apache site. The gpl code doesn’t do much, so I think it’s plausible to replace it with MIT or apache licensed code. I could use some help with: - constructing a full javadoc jar with maven, having the same source contents as the jbake javadoc - figuring out the css and script problems with the embedded javadoc. This is implausible now, since I haven’t pushed the Antora UI project I’m using, but I hope to do this soon. If anyone is interested in working on this I can push them sooner. Embedding the javadoc in the site relies on code I’ve written as an Antora plugin, based on an experimental plugin system I wrote. The idea of a plugin system is accepted for Antora, but my implementation hasn’t been even reviewed yet. ———— In-component organization So far I’ve concentrated on finding and fixing content. I think the next step is to organize the content within the components. The current site seems to use a jbake attribute to programmatically sort pages. While relational databases are great for some things, the AS400 file system has not caught on big time. I’m going to start organizing things by turning these attributes into topic directories or modules. I expect to organize at least some of the other “common” docs into topics or modules. Unless I find a way to easily automate synchronizing the 4 versions of most pages, I’m going to follow (1) and drop the 3 versioned copies. ——————— Examples Currently my treatment of examples relies on a bash script to copy and rename the README.adocs. I’m not sure this is fundamentally worse than what the java code does, it does involve another system. I think it may be possible to write an Antora plugin to directly gather the example files. I suspect this plugin may be of general interest since, for example, most of the camel website is gathered together generated-from-code .adoc files. I haven’t looked much at the example READMEs, but many of them seem to have code copied from the example java files. I’d suggest replacing this with include:: directives. These can specify line numbers or tags in the included files, so we can arrange to leave out the Apache notice :-) Since presumably we want the README to work both in GitHub and in the site, some magic will be needed to get the include:: to work in both places. ————————— Site appearance I’ve been ignoring site appearance until the basic content and organization questions are settled. Antora separates the appearance, or UI, for the site from the content, into a “UI bundle”. At the moment constructing a custom or modified UI bundle is much more difficult and less maintainable than it needs to be. I’m planning to prototype a more flexible system soon. I have a slightly modified default UI bundle for the javadoc content. If someone wants to help with that I can make it available now: otherwise I may wait until using it is simpler. To see what some Antora sites look like, based on customized UI bundles, take a look at the links in https://gitlab.com/antora/antora.org/issues/20 There’s marginally more customization involved, but https://blog.yuzutech.fr/blog/ is also nice. David Jencks
