Lets try all other imaginable, and some unimaginable, methods before we try editing something this complicated on a mailing list :-) I’m happy to try adding comments to the GitHub page.
David Jencks > On Feb 17, 2020, at 2:48 PM, David Blevins <david.blev...@gmail.com> wrote: > > Here’s a copy if you want to go that route. Anything works for me > > > # Proposal: Website 2020 > > This will hopefully serve as the documentation for the website once/if > executed. > > High-level plan > > - Kill all use and trace of the Apache CMS > - Publish html directly to git > - Allow for several sources to publish html > > The result will be several sources, that can be run and managed > independently, feeding content into the git repo housing our live html > website. > > This is a pragmatic perspective that sets us up to get a best-of-breed > outcome acknowledging trends in all our website endevors: > > - All tools we've used have been heavily extended > - Content takes a hit each tool change > - All tools have limitations (strenghts/weaknesses) > - Filling gaps involves extensions (bullet one) > - Tools last on average 2-5 years > - Many types of content actually exist: javadoc, release notes, download pages > - We will always be in a hybrid situation > > Think of it as "microservices for content" and avoiding a monolith. > > Ideally this sets us up to acknowledge and embrace evolving our > website tech without many of the above disadvantages. If we have a > clean CSS and simple menu, we should be able to take HTML from > anywhere. > > When we want to add a new content source we do not need to figure out > how to get it to work "through" the existing generator or redo > everything that already works, we simply have it generate content > directly to html directly to our site git. > > As long as we maintain a common CSS and look and feel, we're good. > > ## Kill all use and trace of the Apache CMS > > TODO > > ## Publish html directly to git > > Apache allows a project to designate a git repository as their > "website." All files in that repository are published as-is to the > internet as the project's website. HTML must be committed to this > repository as it does not offer any generation of any kind. > > TODO: what is the process for getting one of these repos? > TODO: can we get Infra to do a svn-git migration of our current flat-html? > > ## Allow for several sources to publish html > > In the new architecture each content generator publishes rendered html > directly to the site git. > > The following is a rough outline of the types of content: > > - Versioned documentation for a software distribution > - Community/Developer documentation > - Website front-page and "marketing" pages such as major features, > benefits, etc > - Examples > - Javadoc > - Release notes and download pages > - Contributors page > > ### Versioned documentation for a software distribution > > All of our "product documentation" efforts to date have been in some > way wiki-like in nature. They allow any kind of content to take any > shape and do not encourage structure. > > As a result our content is all miscellaneous odds and ends that do not > fit together in any significant chapters or flow. Said another way > we're all "blog" and no "book." > > The proposal for this is to use Antora tied to an effort to create a > documentation outline that encourages contribution on-rails. Gaps in > the documentation should be obvious, which hopefully encourages > contribution > > ### Community/Developer documentation > > Learning how our community works and how to contribute (be a > developer) is also an experience that really needs to be on-rails. > > The proposal for this is to use Antora tied to an effort to create a > deliberately smaller outline of how to get involved. > > This content should be very focused on "developer onboarding", > something all open source projects must nail to grow. > > > ### Website front-page and "marketing" pages, features, etc > > When people come to the website they must get a human-perfect > orientation that gives them the most important information in > highlighted form with the least clicking. > > There is no proven structure for gaining someone's immediate > attention and not losing them. They need to know "why TomEE", > ideally with some pictures or video. There also needs to be > a very small handful of pages to highlight features and further > pull people in. > > The proposal for this is to use the existing Jbake setup as it is > free-form and enforces no structure. These pages must be enabled to > continuously discard/reinvent (revolve vs evolve) and keep trying > different ways to get people's attention. > > ### Examples > > The examples section of the website are arguably the only truly > successful part of the site in its current form. Both the Front-page > and product-documentation parts of the site fall short of > accomplishing what they should do. > > The current library of examples is 180 and growing as the #1 place > where new contributors find success contributing to TomEE. After > improvements made in Dec 2018, contributions over the next 12 months > doubled bringing in over 40 contributors all the examples. > > The proposal for this is to continue the existing Jbake setup as it > has proven to be very successful for this application and more > enhancements are planned, such as: > > - Adding contributors faces to each example page > - Automatically linking code to related online javadoc > - Automatically suggesting related examples > > ### Javadoc > > The current "tomee-site-generator" will clone 34 repositories and > branches across TomEE, Jakarta EE and MicroProfile to generate clean > javadoc trees of each one. > > The Javadoc tree for TomEE is created taking all modules and combining > them into one tree so people get a single, fully-linked javadoc tree > and do not need to be burdened by several small modules. > > The Javadoc tree for Jakarta EE is created in the same spirit, > grabbing the correct release branch of each API and version in Jakarta > EE 8 and combining it together into one fully-linked "jakartaee-8.0" > tree spanning the full platform. > > The Javadoc tree for MicroProfile is created in the same spirit, > grabbing the correct release branch of each API and version in > MicroProfile 2.0 and combining it together into one fully-linked > "microprofile-2.0" tree spanning the full MicroProfile umbrella spec. > > Several motivations exist to grabbing the Jakarta EE and MicroProfile > javadoc and publishing it on the TomEE site. > > - Oracle will no longer publish "javaee" docs. There is no plan > current in the Jakarta EE side of the fence to publish unified > javadoc. There is an industry gap we can fill that will generate > website traffic to TomEE. > - MicroProfile does not current publish fully-combined javadoc. > There is a gab currently. We can fill this as well to provide > value to the industry and generate traffic to TomEE. > - A future plan for our examples is to link code to javadoc. Linking > to javadoc on our own site has the advantage that they never leave > the site and links are guaranteed stable. > - Reverse linking. The javadoc itself can have links to the relevant > examples that show how that class is used. This can be done having > an index of each example, what api classes it uses and then > inserting multiple `@see` links in the source prior to javadoc > generation. > > The proposal is to decouple this code from the current > `tomee-site-generator` code as it is a separate concern, does take a > very long time to generate, and following the spirit of this overall > proposal should be fully independent and not be mixed in with anything > JBake-related. > > ### Release notes and download pages > > The release notes and download page data at one point came entirely > from https://svn.apache.org/repos/asf/tomee/sandbox/release-tools/ > > When this process was working at its best, release notes and download > page entries were generated automatically as part of the release > process. > > Release cadence slowed and these tools decayed due to lack of > knowledge transfer in their existence and how to maintain them. > > As we increase our release cadence we have renewed need to automate > the release overhead of updating download pages and creating release > notes. > > The proposal is to move this code from svn "sandbox" to a proper git > repo and employ automation techniques to cause download pages and > release notes to be automatically updated. This time not by a tool > run by the person doing the release, but by a CI job based on the same > technique we will need to automate publishing of docs or examples when > they are updated. > > The automated job will run on a timer and simply check dist.apache.org > for a new release. It can also be manually triggered and re-run at any > time via the corresponding CI job. > > ### Contributors page > > We have had several attempts at maintaining a contributors page, none > of them successful. > > Manual attempts only reflected some individuals. Automated attempts > were too clever and have broken over time. > > The proposal is to create code to run via a CI job triggered via a git > webhook that simply screen-scrapes this page when the TomEE repo is > updated: > > - https://github.com/apache/tomee/graphs/contributors > > This will allow us to ensure all 98 and growing contributors are > listed and the page is updated when the contributor list changes as > PRs are merged. > > In the future we can potentially do more to encourage contributors by > highlighting them on the TomEE website. > > -- > Sent from my iPhone
