> On Jul 15, 2020, at 3:58 AM, Jonathan Gallimore
> <jonathan.gallim...@gmail.com> wrote:
>
>> I recommend we first eliminate the Apache CMS so we have a hands-free
> setup. Then I recommend we make it so the `tomee-site-generator` maven
> project is the thing that kicks off and runs Antora.
>
> Sounds good to me.
>
>> I seriously don't care what we use for them as the majority of the issues
> are content, not tool. If we need to rollout a tool to motivate people to
> pay attention to the content, let's do it. As long as everything remains
> in Asciidoc we are free to switch at any time, so there's no harm in giving
> it a try.
>
> I agree. I recall there's been some discussion about the navigation
> hierarchy and splitting stuff into "admin" and "developer", and I don't
> think that went anywhere. If we have good content, then the right
> structure will follow. Some way of enumerating what we have so we can
> identify gaps, and review content feels like a potential starting point.
> Seeing what we have on the "old" site that isn't on the "new" site could be
> interesting - if I search for something, I usually get a page from the
> "old" site.
>
AFAIK I’ve found all the “old content”, translated it to Asciidoc, and included
it in the preview Antora site.
David Jencks
> Jon
>
> On Wed, Jul 15, 2020 at 3:35 AM David Blevins <david.blev...@gmail.com>
> wrote:
>
>> Attempting to combine a few threads.
>>
>> - https://github.com/apache/tomee/pull/670#issuecomment-658452277
>>
>> Antora-based website progress
>> -
>> https://lists.apache.org/thread.html/rfbd39e3db0509fe4b8f65e679774699c3b55ae1c3eee5adb72ae551e%40%3Cdev.tomee.apache.org%3E
>>
>> The short version is there was doubt as to if the project was willing to
>> consider using Antora. Cesar's feedback is closest to mine:
>>
>>> - Keep current tomee-site generator as the main content and website
>> layout
>>> - Once set up as a production-ready instance, keep the Antora setup for
>>> the project documentation. This means that the current website link:
>>> https://tomee.apache.org/docs.html will be redirected to the Antora
>>> awesomeness UI.
>>>
>>> keep Antora usage for what it was made for, documentation. Keep JBake
>> for the static website layout and content.
>>
>> I would simply amend that to "Keep JBake for the static website layout and
>> content [and examples.]"
>>
>> I'm very in love with the examples and never was too happy when we
>> switched to JBake and lost the features I had added to supply javadoc
>> links, build instructions and in some cases provide an auto-generated pages
>> for them. We're finally getting those features back into the fold and
>> there are some other cool things I'd like to do such as adding
>> contributor's faces to each example, cross-linking javadoc and examples.
>>
>> Our main docs, however, are a complete mess.
>>
>> I seriously don't care what we use for them as the majority of the issues
>> are content, not tool. If we need to rollout a tool to motivate people to
>> pay attention to the content, let's do it. As long as everything remains
>> in Asciidoc we are free to switch at any time, so there's no harm in giving
>> it a try.
>>
>> I think there are two gaps we need to understand to have a better
>> conversation about using Antora
>>
>> - Eliminating the Apache CMS from our lives. This is the biggest blocker
>> to any true progress. The only reason our site doesn't automatically
>> update now is because we're using the Apache CMS which has a manual publish
>> step that takes about an hour of machine time and periodic manual
>> checking/poking during that time.
>>
>> - Understanding `tomee-site-generator` isn't an enemy to Antora and
>> doesn't need to die or be eliminated. Among other things, we use it to
>> generate asciidoc content when and where we can. It will most likely need
>> to run just before Antora. Antora would be building some mix of manually
>> created docs and some generated docs. If Antora is not capable of
>> committing generated files to git, then `tomee-site-generator` is where we
>> would do that work.
>>
>> I recommend we first eliminate the Apache CMS so we have a hands-free
>> setup. Then I recommend we make it so the `tomee-site-generator` maven
>> project is the thing that kicks off and runs Antora.
>>
>>
>> Thoughts?
>>
>>
>> --
>> David Blevins
>> http://twitter.com/dblevins
>> http://www.tomitribe.com
>>
>>
