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

[David Jencks]

I have a new idea for clarifying the website duplication.

Antora lets you include the same page in several components by using “include 
stubs”, i.e. a page that only has an include:: preprocessor directive, pointing 
to the single copy. (includes work in plain asciidoc, but there’s no practical 
way to refer to the originating page without Antora page coordinates).

Intellij tools such as IDEA and WebStorm have a nice diff fe total.ature and 
customizable live templates.  I made a live template to insert the include:: to 
the “actual copy” of the page.

My workflow is to compare a page in 8.0@tomee (i.e. my antora clone of master 
of the tomee git repo) with the same page in the tomes-site antora branch using 
WebStorm’s side-by-side diff.  I combine the asciidoc to get something that is 
more correct than either source, edit any other errors I see, put the corrected 
version in tomee-site, and replace the tomee master copy with an include stub.

One of the edits is including the jbake attributes from master.

This reduces the number of duplicates by one, and indicates:
- on master that the page is duplicated in common
- on tomee-site that the page is duplicated in master, and edited to look OK.

I now have only 2 errors in 8.0@tomee, 367 in common, and 386 total.

David Jencks

> On Feb 17, 2020, at 4:39 PM, David Jencks  wrote:
> 
> I pushed another preview update.  This has all the content I’ve found and 
> except for a few pages from svn that seem to originate as html and some pages 
> currently generated by the tomee-stie-generator  I believe it has all the 
> content that is supposed to be published.
> 
> There are about 450 errors noted by Antora building this.  These are asciidoc 
> syntax errors (mostly section level errors) and broken links.
> 
> AFAICT most of the content is duplicated in 4 places: what I’m calling 
> “common”, 8.0, 7.1, and 7.0.  Fixing only one copy would be considerably 
> quicker than comparing and fixing 4.
> 
> My extremely biased opinion is that the content is approximately as good 
> shape as the live site.  There is decidedly less organization and navigation. 
>  Some pages are worse, and some are better, but it’s all presented uniformly.
> 
> TomEE Documentation AWS 
> 
> 
> Thanks
> David Jencks
> 
>> On Feb 16, 2020, at 7:41 PM, David Jencks > > wrote:
>> 
>> Thanks for the more info, and I have plenty to do so no hurry, if you do 
>> have some time some quick questions…
>> 
>> is https://svn.apache.org/repos/asf/tomee/site/trunk/content 
>>  the “same as” 
>> the website content, so modulo .md and mdtext > html conversion I can look 
>> at it and act like that’s the website to mimic? (also module files that have 
>> no source)
>> 
>> Is all the source from tomee-site, tomee-site-generator (including 
>> java-generated content), and tomee?  So anything not present in some format 
>> from one of these that’s in the above svn repo can be left out?
>> 
>> I’d think there must be some configuration for the Builder 
>> tomee-site-staging but I can’t find it.
>> 
>> IMO the site in any form is in such a mess that it’s hard to know where to 
>> work first.  There are tons of broken formatting, both in the existing site 
>> and the .adoc translations, and loads of broken links that have no plausible 
>> target.  For instance one of the pages you note  has 
>> 
>> \{include:OPENEJBx30:Singleton Beans}
>> 
>> I didn’t touch that one :-) It’s a bit confusing because there’s no 
>> OPENEJBx30 anywhere in sight, but I expect it’s supposed to refer to the 
>> same component/version.  When I get to it it will turn into a redirect.
>> 
>> I’m mostly concentrating on finding all the sources, getting them into some 
>> sort of semi-coherent structure, and fixing formatting and links that 
>> asciidoctor complains about.  I thought I was nearly done, but now there are 
>> a lot more files :-)
>> 
>> After the automatically recognized problems are fixed, examining the pages 
>> for other problems can start.
>> 
>> Thanks for the hints!
>> 
>> David Jencks
>> 
>> 
>> 
>>> On Feb 16, 2020, at 6:58 PM, David Blevins >> > wrote:
>>> 
>>> Hi David,
>>> 
>>> Looks like you got there in the end.  I attempted to give a heads up on 
>>> that in my first email about the Apache CMS, but all this is complicated.  
>>> Read this then go back and read my first email on the "Documentation Site" 
>>> thread and hopefully it makes more sense.
>>> 
>>> It's very hard to describe it with magically the right level of detail.  
>>> Here's the way too short version.
>>> 
>>> - https://github.com/apache/tomee-site-generator 
>>>  spits html into here
>>> - https://svn.apache.org/repos/asf/tomee/site/trunk/content/ 
>>> 

Re: Draft Proposal for overall website direction

[David Jencks]

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

[Daniel Cunha]

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

[Jonathan Gallimore]

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

[gilbertoca]

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