= 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.