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 Jencks <da...@gmail.com> on 2020/02/15 07:34:26 UTC
Redoing the website with Antora - status
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
Posted by David Jencks <da...@gmail.com>.
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 <da...@gmail.com> 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 <cesarguate@gmail.com <ma...@gmail.com>> 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/ <https://tomee.apache.org/>“ and some at e.g. "https://tomee.apache.org/tomee-8.0/docs/ <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/ <https://tomee.apache.org/tomee-7.0/examples/>
>> [2] https://tomee.apache.org/tomee-7.1/examples/ <https://tomee.apache.org/tomee-7.1/examples/>
>> [3] https://github.com/apache/tomee/tree/tomee-7.0.x/examples <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 <david.a.jencks@gmail.com <ma...@gmail.com>> 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> <
>>> 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
Posted by David Jencks <da...@gmail.com>.
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 <ce...@gmail.com> 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/ <https://tomee.apache.org/>“ and some at e.g. "https://tomee.apache.org/tomee-8.0/docs/ <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 <da...@gmail.com> 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
Posted by Cesar Hernandez <ce...@gmail.com>.
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 <da...@gmail.com> 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