Proposal for a potential direction of the TomEE website
diff --git a/WEBSITE-2020.adoc b/WEBSITE-2020.adoc
new file mode 100644
index 0000000..f600b8b
--- /dev/null
+++ b/WEBSITE-2020.adoc
@@ -0,0 +1,224 @@
+# 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.
