Re: Draft Proposal for overall website direction
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 > >> On Feb 19, 2020, at 5:24 AM, gilbertoca 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
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 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
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.gallim...@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 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
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 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
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
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 wrote: > >> On Feb 18, 2020, at 12:57 PM, Guillermo García 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
> On Feb 18, 2020, at 12:57 PM, Guillermo García 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
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 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 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
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 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
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 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
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
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 >>
Re: Draft Proposal for overall website direction
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
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
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
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
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
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.
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
