writing is hard! Initial comments, too long but at least present
diff --git a/WEBSITE-2020.adoc b/WEBSITE-2020.adoc
index 0356fe9..eaf5b06 100644
--- a/WEBSITE-2020.adoc
+++ b/WEBSITE-2020.adoc
@@ -1,5 +1,6 @@
= Proposal: Website 2020
+
This will hopefully serve as the documentation for the website once/if executed.
High-level plan
@@ -37,10 +38,45 @@
As long as we maintain a common CSS and look and feel, we're good.
-== Kill all use and trace of the Apache CMS
+== DJ
+That's one point of view.
+I agree with a lot of it, but I'm worried...
+Perhaps I can characterize it as thinking that more options are better.
+However, nothing stopped anyone from migrating all the content from CMS to an external .md based system, or from .md to .adoc.
+But no one did it.
+Instead, people piled system on top of system, duplicating content in a partially intelligable state, and reducing the amount of organization and coherence at every step.
+I think reasonable priorities are:
+* as few systems involved in the website as possible
+* avoid extensions and writing our own systems, we don't have time to maintain them let alone document them.
+* organize the input to the website generation process.
+* discourage adding more systems.
+
+My most profound teacher said to pay attention to the balance between structure and behavior.
+We need simple and fairly rigid structure here so behavior can go towards improving the documentation rather than wondering how or why.
+
+I'm very worried about having more than one process push content to the git "website" repo.
+Right now, we effectively have that process with the svn repo, and there's some content that seems to have been added and abandoned.
+No one will tell me about it, including the person who put it there.
+
+As a result, a requirement in my mind is that publishing the website needs to start with deleting everything previously there.
+The next step is adding the entire current content.
+
+Also, "publishing straight to git" actually means committing to a local repository (with tooling this could be bare).
+This gives a preview opportunity, followed by pushing to the apache repo.
+
+'''
+
+== Kill all use and trace of the Apache CMS
TODO
+=== DJ
+
+I think that my antora preview is 99% there.
+Having a second opinion would be valuable, but that could be a time consuming endeavor.
+
+'''
+
== Publish html directly to git
Apache allows a project to designate a git repository as their
@@ -49,13 +85,34 @@
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?
+=== DJ
+
+IMO having the git repo as anything but "staging" will make the process 100% headed for disaster.
+What is this html content?
+
+'''
+
== Allow for several sources to publish html
In the new architecture each content generator publishes rendered html
directly to the site git.
+=== DJ
+Perhaps....
+I think that something more like a maven build is more likely to be useful.
+If there needs to be more than one content generator, then there should be some sort of process to build the entire site and push it to git.
+Without this, no one will be able to understand how the site is built.
+
+For Antora, it's easy to set up a gitlab ci pipeline that builds a site and publishies it on netlify.
+I don't know if anything similar is possible for github, but I thnk it's worth investigating.
+My idea is something like any commit results in updating a preview site.
+If you like it you can push to "master", so asf shows it.
+
+'''
+
The following is a rough outline of the types of content:
* Versioned documentation for a software distribution
@@ -66,6 +123,26 @@
* Release notes and download pages
* Contributors page
+=== DJ
+Another possible division would be
+
+* asciidoc content
+** human written
+** generated
+* non-asciidoc content
+** human written
+** generated
+
+A perpendicular categorization is:
+
+* Stuff that fits well in Antoras's information architecture
+* Stuff that is outside the scope of Antrora's infomration architecture.
+
+While it's easy to regard Antora as an asciidoc processor, IMO its more important contribution is providing a consistent and easy to understand information architecture framework.
+
+
+'''
+
=== Versioned documentation for a software distribution
All of our "product documentation" efforts to date have been in some
@@ -81,6 +158,12 @@
the documentation should be obvious, which hopefully encourages
contribution
+==== DJ
+I suggest we heavily use Antora's structuring abilities, using components, modules, and topics as much as poosible.
+I suggest that we drop any auto-generated TOC or navigation pages and think carefully about organization.
+
+'''
+
=== Community/Developer documentation
Learning how our community works and how to contribute (be a
@@ -92,7 +175,11 @@
This content should be very focused on "developer onboarding",
something all open source projects must nail to grow.
+==== DJ
+My idea is that the "common" component ought to be this, but right now it contains "all the old stuff".
+Some of this indeed appears to be community focused, but a lot is earlier versions of what's also in the versioned component.
+'''
=== Website front-page and "marketing" pages, features, etc
When people come to the website they must get a human-perfect
@@ -110,6 +197,14 @@
continuously discard/reinvent (revolve vs evolve) and keep trying
different ways to get people's attention.
+==== DJ
+I don't know enough about what you have in mind for this content to know what to think.
+There's the front page, which I think is not generated.
+Otherwise, what is this content?
+I'd think if people write it, it will be in asciidoc, and can be rendered with Antora.
+
+'''
+
=== Examples
The examples section of the website are arguably the only truly
@@ -130,6 +225,11 @@
* Automatically linking code to related online javadoc
* Automatically suggesting related examples
+==== DJ
+I'm biased, but how is the jboake setup better than the Antora setup, which I've spent about 0 time on yet?
+Running everything through Antora will assure a uniform appearance and unified navigation.
+
+'''
=== Javadoc
The current "tomee-site-generator" will clone 34 repositories and
@@ -175,6 +275,14 @@
proposal should be fully independent and not be mixed in with anything
JBake-related.
+==== DJ
+I applaud this.
+Once the javadoc is generated, which I would expect only really needs to happen for a release, there's the question of how to get it into the site.
+An advantage of including it in the Antora processed content is that links into it will be checked by Antora while building the site.
+However, at the moment including pregenerated javadoc is not built into Antora although it's an experiment I plan to make soon, and definitely in Antora's future.
+
+'''
+
=== Release notes and download pages
The release notes and download page data at one point came entirely
@@ -202,6 +310,11 @@
for a new release. It can also be manually triggered and re-run at any
time via the corresponding CI job.
+==== DJ
+I wondered where those came from, I'll have to look into this.
+Another workflow would be to have the tool generate asciidoc and commit it to a repository that is an Antora site source, so site builds will automatically include it and it will have consistent appearance.
+
+'''
=== Contributors page
We have had several attempts at maintaining a contributors page, none
@@ -222,3 +335,11 @@
In the future we can potentially do more to encourage contributors by
highlighting them on the TomEE website.
+
+==== DJ
+A better contributors page would be great!
+Screen scraping that github page strikes me as exceedingly fragile.
+Linking to it might be an option!
+I suspect easier than screen-scraping would be extracting the info from git ourselves.
+
+'''
