Ok, it's been a week and the only feedback was positive, so I've gone ahead and merged the changes so we can begin building on them.
- https://github.com/apache/tomee/tree/master/docs - https://github.com/apache/tomee-site-generator/tree/master/src/main/jbake/content At this point, there's nearly an unlimited amount of work that needs to be done :) Perhaps an exaggeration, but it feels that way :) I'll move to getting this published. Some proposals on how to merge all the duplication would be fabulous. A page on Java 11 status could be good. -- David Blevins http://twitter.com/dblevins http://www.tomitribe.com > On Nov 26, 2018, at 3:23 AM, David Blevins <david.blev...@gmail.com> wrote: > > Hi All, > > Our current status with regards to the TomEE website is we have one foot in > each world, old and new. The high-level history is more or less this: > > - 2006-2012 we used Confluence as the "source" and rendered that to html via > a plugin maintained by one brave ASF individual, Pier Paolo Fumagalli. > > - 2012-2016 the ASF discontinued use of confluence like this and everyone > moved to the Apache CMS, maintained by one brave ASF individual, Joe Schaefer. > Each project's code was exported as-is into svn. Joe and I did a bunch of > work to get TomEE setup and was one of the first to use this system. It was > written in perl and basically invented Pull Requests before github and wasn't > a bad solution. We succeeded in fully migrating away from Confluence. We > didn't succeed in fully migrating content from Confluence markup to Markdown. > > - 2016 the ASF discontinued Apache CMS after Joe left. Romain did a lot of > great work to get JBake up and running. JBake is written in Java and can > easily be maintained by us, whereas anything else we've had could not. This > was done "on top" of the old site, with all the old content still there and > decaying. The old content is still generated by the Apache CMS. We didn't > succeeded in fully migrating away from Apache CMS. We now have duplicate > content that confuses us all. > > The JBake work is technically the closest to success I think we've ever seen. > The state of our content, however, is in need of significant love. > > Here are some issues I think have caused repeat failure in all our > documentation attempts: > > - Having just one "source" where documentation lived. > - Mixing general project docs and technical docs. > > When the topic of moving the docs into the main TomEE repo is raised, someone > rightfully says, "what about the general project docs like contribution-tips?" > > When the topic of trying to version the docs outside TomEE, someone says > "that's a huge maintenance nightmare, maybe we can put some kind of 'since > version 1.2.3' on sections of the docs?" > > In the end I think all forms of "one big pile of docs" doesn't work even if > that's git, svn, or confluence. Our current status of "two big piles of > docs", but with no clear line between them, works even less. > > Here's what I've tried to do and this is a work in progress: > > - Merge old and new docs into one "pile" again > - Split out the docs that could be versioned and put them into the main TomEE > repo > - Update our JBake setup so it uses jgit to select content from maintained > TomEE branches & tags > > The Merge: > > - old: https://github.com/apache/tomee-site/tree/trunk/content > - new: > https://github.com/apache/tomee-site-generator/tree/master/src/main/jbake/content > - merged: > https://github.com/dblevins/tomee-site-generator/tree/master/src/main/jbake/content > > The Split: > > Anything that could reasonably be tied to a release has been moved to > "master" of the main TomEE repo: > > - https://github.com/dblevins/tomee/tree/tomee-8.0.x-docs/docs > > The JBake Improvements: > > We just grab from any number of repos and make one directory tree from them > before we pass it to JBake. This gives us these URLs (not live of course, so > don't try to click them): > > - http://tomee.apache.org/tomee-7.0/docs/ > - http://tomee.apache.org/tomee-7.0/examples/ > > - http://tomee.apache.org/tomee-7.1/docs/ > - http://tomee.apache.org/tomee-7.1/examples/ > > - http://tomee.apache.org/tomee-8.0/docs/ > - http://tomee.apache.org/tomee-8.0/examples/ > > - http://tomee.apache.org/latest/docs/ > - http://tomee.apache.org/latest/examples/ > > - http://tomee.apache.org/master/docs/ > - http://tomee.apache.org/master/examples/ > > The intent being 7.0 is feed from the latest tag, which is currently 7.0.5. > When 7.0.6 is released, all "/tomee-7.0/" urls will be rebuilt from the 7.0.6 > tag. Same for 7.1, 8.0, etc. The "latest" allows for a permalink and would > point to what we consider to be the best, likely the tomee-8.0.0-M1 tag. The > "master" is so we can update and publish documentation in conversations with > users and get their feedback prior to release. > > > > This is all early-stage, still prototype, work in progress. Help is > incredibly welcome. You can try out what's there so far, like so: > > $ git clone g...@github.com:dblevins/tomee-site-generator.git > $ cd tomee-site-generator > $ mvn clean compile -Djbake.http=true > > Once that is done, you can open your browser to any of these urls: > > - http://localhost:8080/docs.html > - http://localhost:8080/master/examples/mp-metrics-counted.html > - http://localhost:8080/latest/examples/cdi-basic.html > - http://localhost:8080/tomee-8.0/examples/cdi-basic.html > - http://localhost:8080/tomee-8.0/docs/configuring-javamail.html > > > -- > David Blevins > http://twitter.com/dblevins > http://www.tomitribe.com >
