Re: Redoing the website with Antora - status

[David Jencks]

I thought a bit more about the examples and versioning.

I didn’t check history, but my impression is that once written an example 
doesn’t change; if there’s a new capability to demonstrate, that results in a 
new example. Of course an example might be improved or it’s documentation 
extended, but if it worked on one version of tomee I’d expect it to continue to 
work on all later versions.

If this it true, then I think it would be easier to maintain and use the 
examples documentation if there was one version (“latest” or master) and each 
example had a “since version x.x.x” label.

I think the examples documentation is presented with the non-example 
documentation on the current site, but it is not on my preview site, since the 
“main” documentation is english-only and the examples is multilingual.

Thoughts?

David Jencks

> On Feb 15, 2020, at 6:55 PM, David Jencks  wrote:
> 
> Hi Cesar,
> 
> Thanks for responding!  I’ve been so involved with Antora for so long I 
> forget that not everyone is as familiar with it as I :-)
> 
> If you haven’t already, taking a look at my preview site might help clarify 
> how Antora deals with components and versions - especially the component 
> selector in the lower left.
> 
>> On Feb 15, 2020, at 5:45 PM, Cesar Hernandez > > wrote:
>> 
>> Hi David
>> Thanks for your email and work you are doing.
>> I have a couple of questions:
>> 
>> Combine the remaining pages from tomee-site and tomee-site-generator
>> into an unversioned component
>> 
>> Can you expand please a little bit more what are you referring to as the
>> Unversioned Component? Is this an in-memory process to generate the final
>> source for Anfora?
> 
> I really didn’t explain this!
> 
> Currently the existing web site has some pages at "https://tomee.apache.org/ 
> “ and some at e.g. 
> "https://tomee.apache.org/tomee-8.0/docs/ 
> “.  I’m describing the former as 
> “unversioned” as opposed to the latter which are versioned.
> 
> In an Antora site, a component is normally versioned (like the “tomee-8.0”, 
> although the URL is going to contain something like “tomee/8.0” instead).  
> However, by picking the special version “master” Antora will leave the 
> version segment out of the url, producing and unversioned component.  You can 
> have more versions for that component, but I think that gets confusing.
> 
> It seems to me that some of the documentation is definitely version-specific 
> and some isn’t.  For example, description of the community, how to 
> participate, where git is, etc, aren’t versioned.  So I think having an 
> unversioned component is a good idea.  I was proposing to start off by 
> putting the content that currently isn’t versioned into it.  How this happens 
> isn’t really relevant, but at the moment I’m planning on leaving it in the 
> git repos it is currently in.  That’s probably not a good long term solution, 
> but I think it will make it easier to decide what content can be dropped.
> 
> On the preview site, the “unversioned” content is showing up as tomee version 
> 0.0 and 0.1.  I’m going to combine it into a new unversioned component, 
> perhaps “general”.  I haven’t found a name I really like :-)
> 
>> 
>> * Only have example documentation for 8.0.
>> Does this mean that current documentation for 7.0 [1] and 7.1 [2] won't be
>> available anymore in the website?
>> 
>> In the ticket you mentioned "...Some versions are missing (primarily
>> examples for 7.1 and 7.0).."
>> The current TomEE website generator uses the TomEE branches for getting the
>> examples readme files [3].
>> 
>> 
>> [1] https://tomee.apache.org/tomee-7.0/examples/ 
>> 
>> [2] https://tomee.apache.org/tomee-7.1/examples/ 
>> 
>> [3] https://github.com/apache/tomee/tree/tomee-7.0.x/examples 
>> 
>> 
> 
> Having worked for a couple weeks now on this, my opinion is that the biggest 
> problem the tomee site has is too much duplicated outdated useless content.  
> Maintaining the site has IMO not gone well, so reducing its size may be a 
> good idea.  Certainly the examples documentation seems to be the best 
> maintained part  of the documentation, but I think serious consideration 
> should be given to only showing the examples for the latest version.
> 
> This is just an idea.  If there’s general agreement that the 7.0 and 7.1 
> examples docs should stay on the site, I’m happy to put them in, although it 
> may be some work as they are still in .md format.  I have a pretty good md to 
> adoc  translator but checking the results is definitely needed. I’d likely do 
> this in pieces after the other problems are more solved.  For one thing, it’s 
> really clear where the examples docs come from, and much of my work has been 
> tracking down the source 

Re: Redoing the website with Antora - status

[David Jencks]

Hi Cesar,

Thanks for responding!  I’ve been so involved with Antora for so long I forget 
that not everyone is as familiar with it as I :-)

If you haven’t already, taking a look at my preview site might help clarify how 
Antora deals with components and versions - especially the component selector 
in the lower left.

> On Feb 15, 2020, at 5:45 PM, Cesar Hernandez  wrote:
> 
> Hi David
> Thanks for your email and work you are doing.
> I have a couple of questions:
> 
> Combine the remaining pages from tomee-site and tomee-site-generator
> into an unversioned component
> 
> Can you expand please a little bit more what are you referring to as the
> Unversioned Component? Is this an in-memory process to generate the final
> source for Anfora?

I really didn’t explain this!

Currently the existing web site has some pages at "https://tomee.apache.org/ 
“ and some at e.g. 
"https://tomee.apache.org/tomee-8.0/docs/ 
“.  I’m describing the former as 
“unversioned” as opposed to the latter which are versioned.

In an Antora site, a component is normally versioned (like the “tomee-8.0”, 
although the URL is going to contain something like “tomee/8.0” instead).  
However, by picking the special version “master” Antora will leave the version 
segment out of the url, producing and unversioned component.  You can have more 
versions for that component, but I think that gets confusing.

It seems to me that some of the documentation is definitely version-specific 
and some isn’t.  For example, description of the community, how to participate, 
where git is, etc, aren’t versioned.  So I think having an unversioned 
component is a good idea.  I was proposing to start off by putting the content 
that currently isn’t versioned into it.  How this happens isn’t really 
relevant, but at the moment I’m planning on leaving it in the git repos it is 
currently in.  That’s probably not a good long term solution, but I think it 
will make it easier to decide what content can be dropped.

On the preview site, the “unversioned” content is showing up as tomee version 
0.0 and 0.1.  I’m going to combine it into a new unversioned component, perhaps 
“general”.  I haven’t found a name I really like :-)

> 
> * Only have example documentation for 8.0.
> Does this mean that current documentation for 7.0 [1] and 7.1 [2] won't be
> available anymore in the website?
> 
> In the ticket you mentioned "...Some versions are missing (primarily
> examples for 7.1 and 7.0).."
> The current TomEE website generator uses the TomEE branches for getting the
> examples readme files [3].
> 
> 
> [1] https://tomee.apache.org/tomee-7.0/examples/
> [2] https://tomee.apache.org/tomee-7.1/examples/
> [3] https://github.com/apache/tomee/tree/tomee-7.0.x/examples
> 

Having worked for a couple weeks now on this, my opinion is that the biggest 
problem the tomee site has is too much duplicated outdated useless content.  
Maintaining the site has IMO not gone well, so reducing its size may be a good 
idea.  Certainly the examples documentation seems to be the best maintained 
part  of the documentation, but I think serious consideration should be given 
to only showing the examples for the latest version.

This is just an idea.  If there’s general agreement that the 7.0 and 7.1 
examples docs should stay on the site, I’m happy to put them in, although it 
may be some work as they are still in .md format.  I have a pretty good md to 
adoc  translator but checking the results is definitely needed. I’d likely do 
this in pieces after the other problems are more solved.  For one thing, it’s 
really clear where the examples docs come from, and much of my work has been 
tracking down the source for much of the site!

I hope this clarifies things, and feel free to ask more questions!

David Jencks

> 
> 
> On Sat, Feb 15, 2020 at 01:33 David Jencks  wrote:
> 
>> Hi,
>> 
>> I’ve opened some issues (starting at
>> https://issues.apache.org/jira/browse/TOMEE-2772 <
>> https://issues.apache.org/jira/browse/TOMEE-2772>) about my attempts to
>> build a nice TomEE website with Antora.  There are quite a few questions I
>> still have, and ideally I’ll get some feedback on them soon.  However, I’m
>> about ready to make unilateral decisions on some of them in order to make
>> progress.  At this point this is mostly around which content sources and
>> which parts of these content sources should be included.
>> 
>> In particular, I plan to:
>> 
>> * Stop looking for the source for the files in svnpubsub not in any source
>> I know about
>> * Remove the pages from tomee-site that aren’t in svnpubsub
>> * Combine the remaining pages from tomee-site and tomee-site-generator
>> into an unversioned component
>> * Only have example documentation for 8.0.
>> 
>> Thanks
>> David Jencks

Re: Redoing the website with Antora - status

[Cesar Hernandez]

Hi David
Thanks for your email and work you are doing.
I have a couple of questions:

 Combine the remaining pages from tomee-site and tomee-site-generator
into an unversioned component

Can you expand please a little bit more what are you referring to as the
Unversioned Component? Is this an in-memory process to generate the final
source for Anfora?

* Only have example documentation for 8.0.
Does this mean that current documentation for 7.0 [1] and 7.1 [2] won't be
available anymore in the website?

In the ticket you mentioned "...Some versions are missing (primarily
examples for 7.1 and 7.0).."
The current TomEE website generator uses the TomEE branches for getting the
examples readme files [3].


[1] https://tomee.apache.org/tomee-7.0/examples/
[2] https://tomee.apache.org/tomee-7.1/examples/
[3] https://github.com/apache/tomee/tree/tomee-7.0.x/examples



On Sat, Feb 15, 2020 at 01:33 David Jencks  wrote:

> Hi,
>
> I’ve opened some issues (starting at
> https://issues.apache.org/jira/browse/TOMEE-2772 <
> https://issues.apache.org/jira/browse/TOMEE-2772>) about my attempts to
> build a nice TomEE website with Antora.  There are quite a few questions I
> still have, and ideally I’ll get some feedback on them soon.  However, I’m
> about ready to make unilateral decisions on some of them in order to make
> progress.  At this point this is mostly around which content sources and
> which parts of these content sources should be included.
>
> In particular, I plan to:
>
> * Stop looking for the source for the files in svnpubsub not in any source
> I know about
> * Remove the pages from tomee-site that aren’t in svnpubsub
> * Combine the remaining pages from tomee-site and tomee-site-generator
> into an unversioned component
> * Only have example documentation for 8.0.
>
> Thanks
> David Jencks