You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by David Blevins <da...@gmail.com> on 2020/02/17 05:23:21 UTC
Draft Proposal for overall website direction
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
Posted by Cesar Hernandez <ce...@gmail.com>.
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 (<da...@gmail.com>)
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.
Re: Draft Proposal for overall website direction
Posted by David Jencks <da...@gmail.com>.
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 <da...@gmail.com> 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 <da...@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
>
Re: Draft Proposal for overall website direction
Posted by David Jencks <da...@gmail.com>.
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 <da...@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
Re: Draft Proposal for overall website direction
Posted by David Blevins <da...@gmail.com>.
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
Re: Draft Proposal for overall website direction
Posted by David Blevins <da...@gmail.com>.
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 <db...@tomitribe.com>
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 <da...@gmail.com>
> 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 <da...@gmail.com>
> > 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
Posted by David Blevins <db...@tomitribe.com>.
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 <da...@gmail.com>
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 <da...@gmail.com>
> 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
Posted by David Jencks <da...@gmail.com>.
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 <da...@gmail.com> 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
Posted by David Blevins <da...@gmail.com>.
Everyone should follow Gilberto's example and jump into the conversation.
It's common on open source for two people to race out ahead of everyone. The train looks like it's moving fast and jumping in looks dangerous, so people get intimidated and that compounds. Trains that go too fast often derail.
Jumping even with questions is a huge contribution. You don't need to jump in with an expert opinion. Just jump :)
--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com
> On Feb 18, 2020, at 10:43 AM, gilbertoca <gi...@gmail.com> wrote:
>
> I would stick with jvm tool (jbake) instead of add/learn one
> more(node-antora). Specially I would to suggest we adopt what our Apache
> Netbeans friends have done with jbake (jbake.org) in thier site
> (https://netbeans.apache.org/). There, in each page you have a button ("See
> this page in GitHub") where you/anyone can edit the original asciidoc file
> and make PR for contribution.
>
> Regards,
>
> Gilberto
>
>
> David Blevins-2 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: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
Re: Draft Proposal for overall website direction
Posted by David Jencks <da...@gmail.com>.
Sorry for top posting… I might have a slightly different direction to look in.
Thinking about some of the comments along the lines of “jbake is good enough” I’ve realized that, for me, the main benefit Antora brings over anything else I’m aware of is that it helps you organize your content in a sensible yet very flexible way.
I’d like to draw an analogy to the ant-vs.-maven controversy, if anyone remembers that far back :-) They are both build tools that take your java source and use the java compiler to create class files. Aren’t they just the same then? Well, would you suggest taking TomEE to an ant-based build? Perhaps not…. maven suggests a project organization that makes good sense for most java projects, and does about 70-99% of the organizational work for you.
Perhaps similarly, Antora more or less enforces a simple sensible documentation organization, and provides a simple consistent way to get a nice looking website out with almost no configuration needed.
This documentation project is much larger than I anticipated at first, and the hard part is finding all the content and figuring out a plausible organization. I think I’ve found pretty much everything, and have a preliminary organization. Admittedly I’m strongly biased in favor of Antora, but I would never have considered the project of even collecting all the existing content without the organization Antora provides.
That said, I’m fairly amazed at how much of Antora’s functionality David has compressed into the tomcat-site-generator. However, it’s incomplete, undocumented, unmaintained, and buggy. I suggest that maintaining something like that is not what anyone involved in TomEE wants to be spending their time on.
One possible other factor to consider is that my interest here is primarily in finding out what it’s like to migrate a moderately complex disorganized website to Antora, and investigating what extensions or outside work (such as javadoc) are needed. I’m really not interested in participating in other solutions. I expect to continue until I get something I’m satisfied with or I get tired. I think I already have pretty much all the content as Asciidoctor, and I hope to get it to idiomatic error-free asciidoc. If the community wants a non-Antora solution it should be moderately straightforward to de-Antora-ize the content, but it’s not something I’m likely to be participating in.
In partial answer to David’s last question, I think one reason for the doc decay was allowing too many choices, so that it quickly became too hard to figure out how to do anything.
Thanks
David Jencks
> On Feb 18, 2020, at 1:27 PM, David Blevins <da...@gmail.com> wrote:
>
>> On Feb 18, 2020, at 12:57 PM, Guillermo García <bi...@gmail.com> wrote:
>>
>> I don't want to open a difficult debate about which technology is the best,
>> but in the worst case is it possible to call a committee for a votation?
>> How the TomEE committers team defines which direction to take in these
>> cases?
>
> We definitely still need much more discussion and participation to hammer out all the topics on this. In ideal situations you can find agreement on parts and then reduce the scope of what's being discussed so where people disagree is more clear. That often allows it to be more easily addressed.
>
> When you've done a good job on all that and everyone feels they understand what's being discussed and are all "talked out", it's a definite sign a vote is the only remaining way to move forward and you hold one.
>
> Some projects are pretty strict about whose votes count. Some say just votes from the PMC members count (small group). Some say just the committers (slightly larger). We've typically been pretty open and say everyone's votes count; it's hard to grow a project while telling people who are your future growth, "your vote doesn't count." :)
>
> On this topic specifically, I also agree with David on several things and I definitely don't feel "talked out", so at least for my perspective, we're aways away from voting on anything.
>
> More participation will definitely help the discussion along.
>
> There's an entire facet of this discussion we probably should be talking about which is how to deal with our heaps of content in various states of health; how did it get unhealthy, how do we deal with it, how do we prevent it, how do we encourage more contribution to main docs.
>
> I think any tool in the hands of someone willing to lead an effort to improve our main docs is a good tool.
>
>
> -David
>
>
>
>
>
>
>
>
Re: Draft Proposal for overall website direction
Posted by David Jencks <da...@gmail.com>.
Part of this discussion is about how to organize the website.
I was just pointed to this, which I think has a very nice description of different purposes for different documentation, no matter what technology is used for the site:
https://lisk.io/blog/announcement/lisk-documentation-migrated-asciidoc-and-antora
David Jencks
<snip my previous replies>
>
>> On Feb 19, 2020, at 5:24 AM, gilbertoca <gi...@gmail.com> wrote:
>>
>> David Blevins-2 wrote
>>> There's an entire facet of this discussion we probably should be talking
>>> about which is how to deal with our heaps of content in various states of
>>> health; how did it get unhealthy, how do we deal with it, how do we
>>> prevent it, how do we encourage more contribution to main docs.
>>>
>>> I think any tool in the hands of someone willing to lead an effort to
>>> improve our main docs is a good tool.
>>>
>>> -David
>>
>> We could follow (again) apache friends and others [1] condensing all
>> relevant content in something like a User Guide or Reference Guide - that
>> would help the Maintenance and contribution. This organization can reduce
>> the tooling and it easy integrate(asciidoctor-maven-plugin?) in build
>> system[2].
>>
>> [1]
>> https://netbeans.apache.org/kb/docs/java/index.html
>> https://ci.apache.org/projects/wicket/guide/8.x/single.html
>> https://beanvalidation.org/2.0/spec/
>> https://docs.jboss.org/cdi/spec/2.0/cdi-spec.html
>> https://shiro.apache.org/reference.html
>>
>> [2] https://asciidoctor.org/docs/asciidoctor-maven-plugin/
>>
>> Regards,
>>
>> Gilberto
>>
>>
>>
>> --
>> Sent from: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
>
Re: Draft Proposal for overall website direction
Posted by David Jencks <da...@gmail.com>.
I was more or less assuming that before reorganizing the website content, organizing it was required. Otherwise, you could just drop all current content and start over, which admittedly might be faster and more satisfactory.
The asciidoctor-maven-plugin is only usable if you want a site with only one version. All of the sites you note below indeed only have one version. Although primitive, what David Blevins came up with in tomee-site-generator at least allows multiple versions.
For me, two hard requirements would be:
- generate the entire site in one action. I think this is needed to track what is supposed to be there and avoid orphaned content like we have now.
- support multiple components and versions with easy navigation between them. At a minimum, I think there can be general version less information and version specific information. Separating content into perhaps a User Guide and a Reference Guide would be even better.
Here are some Antora generated sites:
Customized UI:
https://camel.apache.org/manual/latest/getting-started.html / https://github.com/apache/camel/tree/master/docs
https://isis.apache.org/guides/ugfun/ugfun.html (using rather non-standard navigation; I find this confusing) /https://github.com/apache/isis/tree/master/antora (I think this is far too complicated, but it’s one approach to organizing a gigantic disorganized set of documentation)
https://docs.couchbase.com/server/6.5/introduction/intro.html / https://github.com/couchbase/docs-site
https://www.uyuni-project.org/uyuni-docs/uyuni/index.html / https://github.com/uyuni-project/uyuni-docs
Unmodified UI
https://books.japila.pl/apache-spark-internals/apache-spark-internals/latest/index.html / https://github.com/japila-books/apache-spark-internals
There’s a list of more sites here:
https://gitlab.com/antora/antora.org/issues/20
Some of these sites, for reasons I don’t understand, avoid making it clear that there are multiple components and versions. In the default UI, and several of these sites, at the lower left there’s a component selector allowing you to choose which component/version you want to look at.
This is also visible in my preview site.
I’m not aware of any other comparable system that provides built in this level of organization.
David Jencks
> On Feb 19, 2020, at 5:24 AM, gilbertoca <gi...@gmail.com> wrote:
>
> David Blevins-2 wrote
>> There's an entire facet of this discussion we probably should be talking
>> about which is how to deal with our heaps of content in various states of
>> health; how did it get unhealthy, how do we deal with it, how do we
>> prevent it, how do we encourage more contribution to main docs.
>>
>> I think any tool in the hands of someone willing to lead an effort to
>> improve our main docs is a good tool.
>>
>> -David
>
> We could follow (again) apache friends and others [1] condensing all
> relevant content in something like a User Guide or Reference Guide - that
> would help the Maintenance and contribution. This organization can reduce
> the tooling and it easy integrate(asciidoctor-maven-plugin?) in build
> system[2].
>
> [1]
> https://netbeans.apache.org/kb/docs/java/index.html
> https://ci.apache.org/projects/wicket/guide/8.x/single.html
> https://beanvalidation.org/2.0/spec/
> https://docs.jboss.org/cdi/spec/2.0/cdi-spec.html
> https://shiro.apache.org/reference.html
>
> [2] https://asciidoctor.org/docs/asciidoctor-maven-plugin/
>
> Regards,
>
> Gilberto
>
>
>
> --
> Sent from: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
Re: Draft Proposal for overall website direction
Posted by Daniel Cunha <da...@gmail.com>.
I like the ideas as well and I'm totally agree with you Jon.
Em qua., 19 de fev. de 2020 às 10:38, Jonathan Gallimore <
jonathan.gallimore@gmail.com> escreveu:
> I'm not strongly opinionated on the tools to actually generate the content.
> In terms of the organization of the content, I've never quite felt it we
> had right. I know there's been user vs developer and version vs not-version
> discussions in the past.
>
> I quite like the idea of the guide Gilberto has suggested below. If we
> followed that route, I'd still like to see it specific to a TomEE version.
> If it enabled us to provide a complete PDF for offline reading as well,
> that would be amazing. We probably have the content to produce a guide, but
> it would need some re-arranging from what's there I would imagine.
>
> Jon
>
> On Wed, Feb 19, 2020 at 1:24 PM gilbertoca <gi...@gmail.com> wrote:
>
> > David Blevins-2 wrote
> > > There's an entire facet of this discussion we probably should be
> talking
> > > about which is how to deal with our heaps of content in various states
> of
> > > health; how did it get unhealthy, how do we deal with it, how do we
> > > prevent it, how do we encourage more contribution to main docs.
> > >
> > > I think any tool in the hands of someone willing to lead an effort to
> > > improve our main docs is a good tool.
> > >
> > > -David
> >
> > We could follow (again) apache friends and others [1] condensing all
> > relevant content in something like a User Guide or Reference Guide - that
> > would help the Maintenance and contribution. This organization can reduce
> > the tooling and it easy integrate(asciidoctor-maven-plugin?) in build
> > system[2].
> >
> > [1]
> > https://netbeans.apache.org/kb/docs/java/index.html
> > https://ci.apache.org/projects/wicket/guide/8.x/single.html
> > https://beanvalidation.org/2.0/spec/
> > https://docs.jboss.org/cdi/spec/2.0/cdi-spec.html
> > https://shiro.apache.org/reference.html
> >
> > [2] https://asciidoctor.org/docs/asciidoctor-maven-plugin/
> >
> > Regards,
> >
> > Gilberto
> >
> >
> >
> > --
> > Sent from:
> > http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
> >
>
--
Daniel "soro" Cunha
https://twitter.com/dvlc_
Re: Draft Proposal for overall website direction
Posted by Jonathan Gallimore <jo...@gmail.com>.
I'm not strongly opinionated on the tools to actually generate the content.
In terms of the organization of the content, I've never quite felt it we
had right. I know there's been user vs developer and version vs not-version
discussions in the past.
I quite like the idea of the guide Gilberto has suggested below. If we
followed that route, I'd still like to see it specific to a TomEE version.
If it enabled us to provide a complete PDF for offline reading as well,
that would be amazing. We probably have the content to produce a guide, but
it would need some re-arranging from what's there I would imagine.
Jon
On Wed, Feb 19, 2020 at 1:24 PM gilbertoca <gi...@gmail.com> wrote:
> David Blevins-2 wrote
> > There's an entire facet of this discussion we probably should be talking
> > about which is how to deal with our heaps of content in various states of
> > health; how did it get unhealthy, how do we deal with it, how do we
> > prevent it, how do we encourage more contribution to main docs.
> >
> > I think any tool in the hands of someone willing to lead an effort to
> > improve our main docs is a good tool.
> >
> > -David
>
> We could follow (again) apache friends and others [1] condensing all
> relevant content in something like a User Guide or Reference Guide - that
> would help the Maintenance and contribution. This organization can reduce
> the tooling and it easy integrate(asciidoctor-maven-plugin?) in build
> system[2].
>
> [1]
> https://netbeans.apache.org/kb/docs/java/index.html
> https://ci.apache.org/projects/wicket/guide/8.x/single.html
> https://beanvalidation.org/2.0/spec/
> https://docs.jboss.org/cdi/spec/2.0/cdi-spec.html
> https://shiro.apache.org/reference.html
>
> [2] https://asciidoctor.org/docs/asciidoctor-maven-plugin/
>
> Regards,
>
> Gilberto
>
>
>
> --
> Sent from:
> http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
>
Re: Draft Proposal for overall website direction
Posted by gilbertoca <gi...@gmail.com>.
David Blevins-2 wrote
> There's an entire facet of this discussion we probably should be talking
> about which is how to deal with our heaps of content in various states of
> health; how did it get unhealthy, how do we deal with it, how do we
> prevent it, how do we encourage more contribution to main docs.
>
> I think any tool in the hands of someone willing to lead an effort to
> improve our main docs is a good tool.
>
> -David
We could follow (again) apache friends and others [1] condensing all
relevant content in something like a User Guide or Reference Guide - that
would help the Maintenance and contribution. This organization can reduce
the tooling and it easy integrate(asciidoctor-maven-plugin?) in build
system[2].
[1]
https://netbeans.apache.org/kb/docs/java/index.html
https://ci.apache.org/projects/wicket/guide/8.x/single.html
https://beanvalidation.org/2.0/spec/
https://docs.jboss.org/cdi/spec/2.0/cdi-spec.html
https://shiro.apache.org/reference.html
[2] https://asciidoctor.org/docs/asciidoctor-maven-plugin/
Regards,
Gilberto
--
Sent from: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
Re: Draft Proposal for overall website direction
Posted by David Blevins <da...@gmail.com>.
> On Feb 18, 2020, at 12:57 PM, Guillermo García <bi...@gmail.com> wrote:
>
> I don't want to open a difficult debate about which technology is the best,
> but in the worst case is it possible to call a committee for a votation?
> How the TomEE committers team defines which direction to take in these
> cases?
We definitely still need much more discussion and participation to hammer out all the topics on this. In ideal situations you can find agreement on parts and then reduce the scope of what's being discussed so where people disagree is more clear. That often allows it to be more easily addressed.
When you've done a good job on all that and everyone feels they understand what's being discussed and are all "talked out", it's a definite sign a vote is the only remaining way to move forward and you hold one.
Some projects are pretty strict about whose votes count. Some say just votes from the PMC members count (small group). Some say just the committers (slightly larger). We've typically been pretty open and say everyone's votes count; it's hard to grow a project while telling people who are your future growth, "your vote doesn't count." :)
On this topic specifically, I also agree with David on several things and I definitely don't feel "talked out", so at least for my perspective, we're aways away from voting on anything.
More participation will definitely help the discussion along.
There's an entire facet of this discussion we probably should be talking about which is how to deal with our heaps of content in various states of health; how did it get unhealthy, how do we deal with it, how do we prevent it, how do we encourage more contribution to main docs.
I think any tool in the hands of someone willing to lead an effort to improve our main docs is a good tool.
-David
Re: Draft Proposal for overall website direction
Posted by Guillermo García <bi...@gmail.com>.
Hi Hilberto,
I have been following some David's ideas and I agree with him in the
direction of using Antora. I consider Antora in a mature state to let us
manage the website efficiently. And I am not worried about learning a new
tool, even if it is jbake.
I don't want to open a difficult debate about which technology is the best,
but in the worst case is it possible to call a committee for a votation?
How the TomEE committers team defines which direction to take in these
cases?
Best,
Guillermo
On Tue, Feb 18, 2020, 2:49 PM David Jencks <da...@gmail.com> wrote:
> Antora already supports “edit this page". Some pages in the current site
> have a button for it, but I don’t know if it works.
>
> David Jencks
>
> > On Feb 18, 2020, at 10:43 AM, gilbertoca <gi...@gmail.com> wrote:
> >
> > I would stick with jvm tool (jbake) instead of add/learn one
> > more(node-antora). Specially I would to suggest we adopt what our Apache
> > Netbeans friends have done with jbake (jbake.org) in thier site
> > (https://netbeans.apache.org/). There, in each page you have a button
> ("See
> > this page in GitHub") where you/anyone can edit the original asciidoc
> file
> > and make PR for contribution.
> >
> > Regards,
> >
> > Gilberto
> >
> >
> > David Blevins-2 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:
> http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
>
>
Re: Draft Proposal for overall website direction
Posted by David Jencks <da...@gmail.com>.
Antora already supports “edit this page". Some pages in the current site have a button for it, but I don’t know if it works.
David Jencks
> On Feb 18, 2020, at 10:43 AM, gilbertoca <gi...@gmail.com> wrote:
>
> I would stick with jvm tool (jbake) instead of add/learn one
> more(node-antora). Specially I would to suggest we adopt what our Apache
> Netbeans friends have done with jbake (jbake.org) in thier site
> (https://netbeans.apache.org/). There, in each page you have a button ("See
> this page in GitHub") where you/anyone can edit the original asciidoc file
> and make PR for contribution.
>
> Regards,
>
> Gilberto
>
>
> David Blevins-2 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: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
Re: Draft Proposal for overall website direction
Posted by gilbertoca <gi...@gmail.com>.
I would stick with jvm tool (jbake) instead of add/learn one
more(node-antora). Specially I would to suggest we adopt what our Apache
Netbeans friends have done with jbake (jbake.org) in thier site
(https://netbeans.apache.org/). There, in each page you have a button ("See
this page in GitHub") where you/anyone can edit the original asciidoc file
and make PR for contribution.
Regards,
Gilberto
David Blevins-2 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: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html