Hi David, I think this is a great start, I built the project here and works.
Now the challenge will be to format in a way the content structure looks nice, as it has bullets with simple names. We need to add a descriptive name and better the design of the page in my opinion. Maybe asking help for some web designer on how to make the page better. I really think we can't just put all the examples there. We need to think in a broader way and ask ourselves. "If I am starting with TomEE, what do I need to know"? "Where can I download TomEE", "What are the differences between flavors?", "What Java version is needed"? "What IDEs support TomEE?", "How can I use it in Eclipse?" We need to try to guess what the developer is looking for when he is starting and then after we helped him to bootstrap we will have advanced content and examples. Also there will be some work to be done to identify which articles fall into each TomEE version. Count on me with this, if you need help in a specific task let me know. On Mon, Nov 26, 2018 at 9:23 AM David Blevins <[email protected]> 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 [email protected]: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 > >
