[GitHub] [tomee-site-generator] djencks merged pull request #19: Website 2020 - some initial too long and unfocused comments, but at least written down.

[GitBox]

djencks merged pull request #19: Website 2020 - some initial too long and 
unfocused comments, but at least written down.
URL: https://github.com/apache/tomee-site-generator/pull/19
 
 
   


This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services

Re: Draft Proposal for overall website direction

[David Jencks]

I wrote some overly long and unfocussed comments, and pushed them to my fork 
and opened a PR.  I don’t seem to have permissions to merge…. did I follow the 
wrong procedure (e.g. should I make a branch and merge from  that) or do I not 
have appropriate permissions?  Maybe my GitHub identity is not appropriately 
lined up with my Apache identity?

Thanks
David Jencks


> On Feb 17, 2020, at 3:50 PM, David Jencks  wrote:
> 
> 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  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
>> 

[GitHub] [tomee-site-generator] djencks opened a new pull request #19: Website 2020 - some initial too long and unfocused comments, but at least written down.

[GitBox]

djencks opened a new pull request #19: Website 2020 - some initial too long and 
unfocused comments, but at least written down.
URL: https://github.com/apache/tomee-site-generator/pull/19
 
 
   


This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


With regards,
Apache Git Services

Re: (new) website content sanity check :-)

[David Jencks]

I pushed another preview update.  This has all the content I’ve found and 
except for a few pages from svn that seem to originate as html and some pages 
currently generated by the tomee-stie-generator  I believe it has all the 
content that is supposed to be published.

There are about 450 errors noted by Antora building this.  These are asciidoc 
syntax errors (mostly section level errors) and broken links.

AFAICT most of the content is duplicated in 4 places: what I’m calling 
“common”, 8.0, 7.1, and 7.0.  Fixing only one copy would be considerably 
quicker than comparing and fixing 4.

My extremely biased opinion is that the content is approximately as good shape 
as the live site.  There is decidedly less organization and navigation.  Some 
pages are worse, and some are better, but it’s all presented uniformly.

TomEE Documentation AWS 


Thanks
David Jencks

> On Feb 16, 2020, at 7:41 PM, David Jencks  wrote:
> 
> Thanks for the more info, and I have plenty to do so no hurry, if you do have 
> some time some quick questions…
> 
> is https://svn.apache.org/repos/asf/tomee/site/trunk/content 
>  the “same as” the 
> website content, so modulo .md and mdtext > html conversion I can look at it 
> and act like that’s the website to mimic? (also module files that have no 
> source)
> 
> Is all the source from tomee-site, tomee-site-generator (including 
> java-generated content), and tomee?  So anything not present in some format 
> from one of these that’s in the above svn repo can be left out?
> 
> I’d think there must be some configuration for the Builder tomee-site-staging 
> but I can’t find it.
> 
> IMO the site in any form is in such a mess that it’s hard to know where to 
> work first.  There are tons of broken formatting, both in the existing site 
> and the .adoc translations, and loads of broken links that have no plausible 
> target.  For instance one of the pages you note  has 
> 
> \{include:OPENEJBx30:Singleton Beans}
> 
> I didn’t touch that one :-) It’s a bit confusing because there’s no 
> OPENEJBx30 anywhere in sight, but I expect it’s supposed to refer to the same 
> component/version.  When I get to it it will turn into a redirect.
> 
> I’m mostly concentrating on finding all the sources, getting them into some 
> sort of semi-coherent structure, and fixing formatting and links that 
> asciidoctor complains about.  I thought I was nearly done, but now there are 
> a lot more files :-)
> 
> After the automatically recognized problems are fixed, examining the pages 
> for other problems can start.
> 
> Thanks for the hints!
> 
> David Jencks
> 
> 
> 
>> On Feb 16, 2020, at 6:58 PM, David Blevins > > wrote:
>> 
>> Hi David,
>> 
>> Looks like you got there in the end.  I attempted to give a heads up on that 
>> in my first email about the Apache CMS, but all this is complicated.  Read 
>> this then go back and read my first email on the "Documentation Site" thread 
>> and hopefully it makes more sense.
>> 
>> It's very hard to describe it with magically the right level of detail.  
>> Here's the way too short version.
>> 
>> - https://github.com/apache/tomee-site-generator 
>>  spits html into here
>> - https://svn.apache.org/repos/asf/tomee/site/trunk/content/ 
>>  which triggers 
>> this Apache CMS job
>> - https://ci.apache.org/builders/tomee-site-staging 
>>  which takes any html and 
>> also converts the mdtext and puts them here
>> - /usr/local/websites/tomee/trunk which is a private svn repo that publishes 
>> to here
>> - http://tomee.staging.apache.org  which 
>> can only get published if a human visits here
>> - https://cms.apache.org/tomee/publish 
>>  and clicks the button so all html 
>> (CMS and otherwise) get published here
>> - http://tomee.apache.org/ 
>> 
>> What we truly need more than a switch from Jbake to Antora is to get rid of 
>> the Apache CMS as that would cut out 4 of those 7 bullets leaving us with:
>> 
>> - https://github.com/apache/tomee-site-generator 
>>  spits html into here
>> - https://github.com/apache/tomee- 
>>  which causes Apache's 
>> new infra to publish here
>> - http://tomee.apache.org/ 
>> 
>> Unfortunately this repo appears to be a honeypot (dead end that can only 
>> confuse).  It used to be a mirror of 
>> svn.apache.org/repos/asf/tomee/site/trunk/content 
>> , but it looks 
>> like the sync stopped about 2 years ago.
>> 
>> 
>> All the work of the last 10 

Re: Draft Proposal for overall website direction

[David Jencks]

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

Re: Draft Proposal for overall website direction

[David Blevins]

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 

Re: Draft Proposal for overall website direction

[David Blevins]

Wheels rolling but quick thought, maybe I just copy/paste it here and use
the list and maybe update it periodically?

I’m open.

On Mon, Feb 17, 2020 at 4:32 PM David Blevins 
wrote:

> Hello from the tarmac in IAH!
>
> That works.  Maybe even I should back it out and resubmit as a PR and we
> can use the comments?
>
> Dig in whichever way and we can adjust if it gets awkward.  My primary
> motivation was fear of it being not digestible without formatting.
>
> Started a response to your other questions, but got cut short on the last
> flight and this one is too small for wifi. I have some commits in mind that
> I think help clarify where we are at in terms of various things being in
> various states of progress.  On cell so will do that hopefully tonight.
>
> On Mon, Feb 17, 2020 at 4:20 PM David Jencks 
> wrote:
>
> > What would you consider the best way of providing detailed comments on
> > this?  Perhaps editing the document adding subsections or sublist items
> > with my initials?
> >
> > Thanks
> > David Jencks
> >
> > > On Feb 16, 2020, at 9:23 PM, David Blevins 
> > wrote:
> > >
> > > All,
> > >
> > > I have a draft of something we can kick around for our website overall.
> > >
> > > -
> >
> https://github.com/apache/tomee-site-generator/blob/master/WEBSITE-2020.adoc
> > >
> > > This took 3 hours to write so apologies for the size.  Much of this is
> > experience from all the efforts of the past, some imagined improvements
> to
> > successful parts of the site, while paving the way for the Antora work.
> > >
> > > Food on the table, cranky wife!  Must go!
> > >
> > > Sorry for the short email! :)
> > >
> > >
> > > --
> > > David Blevins
> > > http://twitter.com/dblevins
> > > http://www.tomitribe.com
> > >
> >
> > --
> Sent from Gmail Mobile
>
-- 
Sent from my iPhone

Re: Draft Proposal for overall website direction

[David Blevins]

Hello from the tarmac in IAH!

That works.  Maybe even I should back it out and resubmit as a PR and we
can use the comments?

Dig in whichever way and we can adjust if it gets awkward.  My primary
motivation was fear of it being not digestible without formatting.

Started a response to your other questions, but got cut short on the last
flight and this one is too small for wifi. I have some commits in mind that
I think help clarify where we are at in terms of various things being in
various states of progress.  On cell so will do that hopefully tonight.

On Mon, Feb 17, 2020 at 4:20 PM David Jencks 
wrote:

> What would you consider the best way of providing detailed comments on
> this?  Perhaps editing the document adding subsections or sublist items
> with my initials?
>
> Thanks
> David Jencks
>
> > On Feb 16, 2020, at 9:23 PM, David Blevins 
> wrote:
> >
> > All,
> >
> > I have a draft of something we can kick around for our website overall.
> >
> > -
> https://github.com/apache/tomee-site-generator/blob/master/WEBSITE-2020.adoc
> >
> > This took 3 hours to write so apologies for the size.  Much of this is
> experience from all the efforts of the past, some imagined improvements to
> successful parts of the site, while paving the way for the Antora work.
> >
> > Food on the table, cranky wife!  Must go!
> >
> > Sorry for the short email! :)
> >
> >
> > --
> > David Blevins
> > http://twitter.com/dblevins
> > http://www.tomitribe.com
> >
>
> --
Sent from Gmail Mobile

Re: Draft Proposal for overall website direction

[David Jencks]

What would you consider the best way of providing detailed comments on this?  
Perhaps editing the document adding subsections or sublist items with my 
initials?

Thanks
David Jencks

> On Feb 16, 2020, at 9:23 PM, David Blevins  wrote:
> 
> All,
> 
> I have a draft of something we can kick around for our website overall.
> 
> - https://github.com/apache/tomee-site-generator/blob/master/WEBSITE-2020.adoc
> 
> This took 3 hours to write so apologies for the size.  Much of this is 
> experience from all the efforts of the past, some imagined improvements to 
> successful parts of the site, while paving the way for the Antora work.
> 
> Food on the table, cranky wife!  Must go!
> 
> Sorry for the short email! :)
> 
> 
> -- 
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
> 

Re: Draft Proposal for overall website direction

[Cesar Hernandez]

I think the compatibility matrix can be also added into the "Release notes
and download pages" or in the separated section.

We have a couple of tickets related to this and the spirit behind is that
we can automate the pom scanning of a specific TomEE version and provide a
compatibility matrix that includes not just JakartaEE but also MicroProfile
compatibility visibility.


El dom., 16 feb. 2020 a las 23:23, David Blevins ()
escribió:

> All,
>
> I have a draft of something we can kick around for our website overall.
>
>  -
> https://github.com/apache/tomee-site-generator/blob/master/WEBSITE-2020.adoc
>
> This took 3 hours to write so apologies for the size.  Much of this is
> experience from all the efforts of the past, some imagined improvements to
> successful parts of the site, while paving the way for the Antora work.
>
> Food on the table, cranky wife!  Must go!
>
> Sorry for the short email! :)
>
>
> --
> David Blevins
> http://twitter.com/dblevins
> http://www.tomitribe.com
>
>

-- 
Atentamente:
César Hernández.