Sorry for top posting… I might have a slightly different direction to look in.
Thinking about some of the comments along the lines of “jbake is good enough” I’ve realized that, for me, the main benefit Antora brings over anything else I’m aware of is that it helps you organize your content in a sensible yet very flexible way. I’d like to draw an analogy to the ant-vs.-maven controversy, if anyone remembers that far back :-) They are both build tools that take your java source and use the java compiler to create class files. Aren’t they just the same then? Well, would you suggest taking TomEE to an ant-based build? Perhaps not…. maven suggests a project organization that makes good sense for most java projects, and does about 70-99% of the organizational work for you. Perhaps similarly, Antora more or less enforces a simple sensible documentation organization, and provides a simple consistent way to get a nice looking website out with almost no configuration needed. This documentation project is much larger than I anticipated at first, and the hard part is finding all the content and figuring out a plausible organization. I think I’ve found pretty much everything, and have a preliminary organization. Admittedly I’m strongly biased in favor of Antora, but I would never have considered the project of even collecting all the existing content without the organization Antora provides. That said, I’m fairly amazed at how much of Antora’s functionality David has compressed into the tomcat-site-generator. However, it’s incomplete, undocumented, unmaintained, and buggy. I suggest that maintaining something like that is not what anyone involved in TomEE wants to be spending their time on. One possible other factor to consider is that my interest here is primarily in finding out what it’s like to migrate a moderately complex disorganized website to Antora, and investigating what extensions or outside work (such as javadoc) are needed. I’m really not interested in participating in other solutions. I expect to continue until I get something I’m satisfied with or I get tired. I think I already have pretty much all the content as Asciidoctor, and I hope to get it to idiomatic error-free asciidoc. If the community wants a non-Antora solution it should be moderately straightforward to de-Antora-ize the content, but it’s not something I’m likely to be participating in. In partial answer to David’s last question, I think one reason for the doc decay was allowing too many choices, so that it quickly became too hard to figure out how to do anything. Thanks David Jencks > On Feb 18, 2020, at 1:27 PM, David Blevins <david.blev...@gmail.com> wrote: > >> On Feb 18, 2020, at 12:57 PM, Guillermo García <bitco...@gmail.com> wrote: >> >> I don't want to open a difficult debate about which technology is the best, >> but in the worst case is it possible to call a committee for a votation? >> How the TomEE committers team defines which direction to take in these >> cases? > > We definitely still need much more discussion and participation to hammer out > all the topics on this. In ideal situations you can find agreement on parts > and then reduce the scope of what's being discussed so where people disagree > is more clear. That often allows it to be more easily addressed. > > When you've done a good job on all that and everyone feels they understand > what's being discussed and are all "talked out", it's a definite sign a vote > is the only remaining way to move forward and you hold one. > > Some projects are pretty strict about whose votes count. Some say just votes > from the PMC members count (small group). Some say just the committers > (slightly larger). We've typically been pretty open and say everyone's votes > count; it's hard to grow a project while telling people who are your future > growth, "your vote doesn't count." :) > > On this topic specifically, I also agree with David on several things and I > definitely don't feel "talked out", so at least for my perspective, we're > aways away from voting on anything. > > More participation will definitely help the discussion along. > > 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 > > > > > > > >
