> 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. 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 > >
