Re: Merging Old and New Websites - Volunteers Needed
It looks super cool :) On Mon, Dec 3, 2018 at 4:28 AM Karan Malhi wrote: > I will start taking a look at these this week. > > On Sun, Dec 2, 2018 at 4:07 AM David Blevins > wrote: > > > > On Dec 1, 2018, at 5:41 PM, David Blevins > > wrote: > > > > > > I'm attempting to get this to a point where we can crowd source some > > non-automatable tasks. > > [...] > > > To get there I just need to 1) minimally improve the index pages to > have > > groups and 2) add the jbake headers to all the files > > > > Ok, indexing is in and JBake headers added. > > > > - http://tomee.apache.org/tomee-8.0/docs/ > > - http://tomee.apache.org/tomee-8.0/examples/ > > > > Those preliminary groups are not anything near polished. Consider them > > inspiration, but restriction. Feel free dramatically change the groups. > > My intent is to do enough to show what can be done so others can be > > productive. > > > > > What I'm imaging we can all do in a divide and conquer fashion: > > > > > > - Categorize each document for an intelligent looking index > > > - Review each document for formatting issues > > > - Convert markdown documents to asciidoc > > > - Fix inconsistent h1, h2, h3 etc usage > > > - Update branding to "TomEE" from "OpenEJB" > > > - Ensure each has a title > > > - Check links > > > > Open season on docs. Let the PRs fly! What we need is people to dig in > > here and here: > > > > - https://github.com/apache/tomee/tree/master/docs > > - https://github.com/apache/tomee/tree/master/examples > > > > And create PRs like these commits: > > > > - > > > https://github.com/apache/tomee/commit/bdee81d34c60644b755621254a535d0d8757eb21 > > - > > > https://github.com/apache/tomee/commit/e2190a47c211c870680d761efd6d025d935546c7 > > > > While you're in there, make sure the document has a "title=Foo" > > > > I cannot stress enough the groupings you see do not reflect human action, > > so do not get fussed with questions like "Why didn't he group this one as > > CDI, it's clearly CDI???" I took an old index that was a bout 5 years > > stale and used it to seed the groups like so: > > > > - > > > https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/AddGroups.java > > > > So what you see a machine could do and did. We need humans to put some > > thought into the best way to organize and put groups in that make sense. > > > > If you'd like to build the docs locally, run this long command and then > > open your browser to http://localhost:8080 > > > > - git clone g...@github.com:apache/tomee-site-generator.git && cd > > tomee-site-generator && mvn clean compile -Djbake.http=true > > > > That will clone the site repo and build it, which will in turn pull down > > all the related TomEE branches. > > > > > > -David > > > > > > -- > > Karan Singh Malhi >
Re: Merging Old and New Websites - Volunteers Needed
I will start taking a look at these this week. On Sun, Dec 2, 2018 at 4:07 AM David Blevins wrote: > > On Dec 1, 2018, at 5:41 PM, David Blevins > wrote: > > > > I'm attempting to get this to a point where we can crowd source some > non-automatable tasks. > [...] > > To get there I just need to 1) minimally improve the index pages to have > groups and 2) add the jbake headers to all the files > > Ok, indexing is in and JBake headers added. > > - http://tomee.apache.org/tomee-8.0/docs/ > - http://tomee.apache.org/tomee-8.0/examples/ > > Those preliminary groups are not anything near polished. Consider them > inspiration, but restriction. Feel free dramatically change the groups. > My intent is to do enough to show what can be done so others can be > productive. > > > What I'm imaging we can all do in a divide and conquer fashion: > > > > - Categorize each document for an intelligent looking index > > - Review each document for formatting issues > > - Convert markdown documents to asciidoc > > - Fix inconsistent h1, h2, h3 etc usage > > - Update branding to "TomEE" from "OpenEJB" > > - Ensure each has a title > > - Check links > > Open season on docs. Let the PRs fly! What we need is people to dig in > here and here: > > - https://github.com/apache/tomee/tree/master/docs > - https://github.com/apache/tomee/tree/master/examples > > And create PRs like these commits: > > - > https://github.com/apache/tomee/commit/bdee81d34c60644b755621254a535d0d8757eb21 > - > https://github.com/apache/tomee/commit/e2190a47c211c870680d761efd6d025d935546c7 > > While you're in there, make sure the document has a "title=Foo" > > I cannot stress enough the groupings you see do not reflect human action, > so do not get fussed with questions like "Why didn't he group this one as > CDI, it's clearly CDI???" I took an old index that was a bout 5 years > stale and used it to seed the groups like so: > > - > https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/AddGroups.java > > So what you see a machine could do and did. We need humans to put some > thought into the best way to organize and put groups in that make sense. > > If you'd like to build the docs locally, run this long command and then > open your browser to http://localhost:8080 > > - git clone g...@github.com:apache/tomee-site-generator.git && cd > tomee-site-generator && mvn clean compile -Djbake.http=true > > That will clone the site repo and build it, which will in turn pull down > all the related TomEE branches. > > > -David > > -- Karan Singh Malhi
Re: Merging Old and New Websites
Hello David, Done: JIRA 2307 to JIRA 2311 created (yes, that's 5 JIRAs in a row) to capture these requirements on documentation / overall TomEE site layout. May the force be with Web Designers! Kind regards, Alexandre Le dim. 2 déc. 2018 à 13:27, David Blevins a écrit : > > These are all great suggestions. If you can file them as jiras of type > "documentation" that would be very helpful. > > > On Dec 1, 2018, at 11:56 PM, Alex The Rocker wrote: > > > > 1. This site must have navigation links, or better : breadcrumbs > > link, in all its pages. > > Let me take an example: when I click on the link you gave as an > > example: > > http://tomee.apache.org/tomee-7.1/examples/application-composer.html, > > I arrive on a page which is missing the "context" : I should see that > > I am in a documentation page for TomEE version 7.1, subsection > > Examples, and I should be allowed to navigate from this page to "The > > root of all TomEE docs / The root of all TomEE 71 docs / The root of > > all Examples of TomEE 7.1 docs". > > Alternative would be to show a TOC (Table Of Contents) next to > > all pages, but I personally find TOCs takes to much reading space, > > whereas breadcrumbs, if well designed (don't use too long identified > > for each "nesting") only take a short space, usual at the top of the > > displayed page (but under other navigation elements, like the Search > > bar, see #3 below). > > We should definitely get that in there. I'll be moving on to see if we can > get javadoc in, but if someone wants to hack this is a great task. > > > > 2. It would be nice to have (not mandatory) a way to switch from > > version 7.1 of this page to 7.0 and 8.0. > > > > 3. A missing feature is a Search bar in the top of all pages, > > allowing to search documentation / examples on TomEE site. > > > > 4. Would it be possible to add a "day / night switch button" ? (see > > the Sun/Moon icon at the top right hand side of this site: > > https://docs.influxdata.com/telegraf/v1.9/data_formats/template-patterns/), > > I love this one, but it's a matter of taste here :) > > Way out of my skill, but perhaps there's an enthusiastic developer out there > :) > > > 5. (hard) Access to the site from mobiles sucks, requires zooming. > > Ideally the styles should implement responsive web design to nicely > > fit pages in small displays. > > We're using twitter bootstrap, which should be responsive except for tables. > There's no way to make tables responsive as far as I know. > > The margins look a little tight on the mobile version which should be > tweaked, but other than that it looks responsive. If you have a couple pages > that don't look good (tables aside), that would be helpful. > > > -David >
Re: Merging Old and New Websites
These are all great suggestions. If you can file them as jiras of type "documentation" that would be very helpful. > On Dec 1, 2018, at 11:56 PM, Alex The Rocker wrote: > > 1. This site must have navigation links, or better : breadcrumbs > link, in all its pages. > Let me take an example: when I click on the link you gave as an > example: http://tomee.apache.org/tomee-7.1/examples/application-composer.html, > I arrive on a page which is missing the "context" : I should see that > I am in a documentation page for TomEE version 7.1, subsection > Examples, and I should be allowed to navigate from this page to "The > root of all TomEE docs / The root of all TomEE 71 docs / The root of > all Examples of TomEE 7.1 docs". > Alternative would be to show a TOC (Table Of Contents) next to > all pages, but I personally find TOCs takes to much reading space, > whereas breadcrumbs, if well designed (don't use too long identified > for each "nesting") only take a short space, usual at the top of the > displayed page (but under other navigation elements, like the Search > bar, see #3 below). We should definitely get that in there. I'll be moving on to see if we can get javadoc in, but if someone wants to hack this is a great task. > 2. It would be nice to have (not mandatory) a way to switch from > version 7.1 of this page to 7.0 and 8.0. > > 3. A missing feature is a Search bar in the top of all pages, > allowing to search documentation / examples on TomEE site. > > 4. Would it be possible to add a "day / night switch button" ? (see > the Sun/Moon icon at the top right hand side of this site: > https://docs.influxdata.com/telegraf/v1.9/data_formats/template-patterns/), > I love this one, but it's a matter of taste here :) Way out of my skill, but perhaps there's an enthusiastic developer out there :) > 5. (hard) Access to the site from mobiles sucks, requires zooming. > Ideally the styles should implement responsive web design to nicely > fit pages in small displays. We're using twitter bootstrap, which should be responsive except for tables. There's no way to make tables responsive as far as I know. The margins look a little tight on the mobile version which should be tweaked, but other than that it looks responsive. If you have a couple pages that don't look good (tables aside), that would be helpful. -David
Re: Merging Old and New Websites - Volunteers Needed
> On Dec 1, 2018, at 5:41 PM, David Blevins wrote: > > I'm attempting to get this to a point where we can crowd source some > non-automatable tasks. [...] > To get there I just need to 1) minimally improve the index pages to have > groups and 2) add the jbake headers to all the files Ok, indexing is in and JBake headers added. - http://tomee.apache.org/tomee-8.0/docs/ - http://tomee.apache.org/tomee-8.0/examples/ Those preliminary groups are not anything near polished. Consider them inspiration, but restriction. Feel free dramatically change the groups. My intent is to do enough to show what can be done so others can be productive. > What I'm imaging we can all do in a divide and conquer fashion: > > - Categorize each document for an intelligent looking index > - Review each document for formatting issues > - Convert markdown documents to asciidoc > - Fix inconsistent h1, h2, h3 etc usage > - Update branding to "TomEE" from "OpenEJB" > - Ensure each has a title > - Check links Open season on docs. Let the PRs fly! What we need is people to dig in here and here: - https://github.com/apache/tomee/tree/master/docs - https://github.com/apache/tomee/tree/master/examples And create PRs like these commits: - https://github.com/apache/tomee/commit/bdee81d34c60644b755621254a535d0d8757eb21 - https://github.com/apache/tomee/commit/e2190a47c211c870680d761efd6d025d935546c7 While you're in there, make sure the document has a "title=Foo" I cannot stress enough the groupings you see do not reflect human action, so do not get fussed with questions like "Why didn't he group this one as CDI, it's clearly CDI???" I took an old index that was a bout 5 years stale and used it to seed the groups like so: - https://github.com/apache/tomee-site-generator/blob/master/src/main/java/org/apache/tomee/website/AddGroups.java So what you see a machine could do and did. We need humans to put some thought into the best way to organize and put groups in that make sense. If you'd like to build the docs locally, run this long command and then open your browser to http://localhost:8080 - git clone g...@github.com:apache/tomee-site-generator.git && cd tomee-site-generator && mvn clean compile -Djbake.http=true That will clone the site repo and build it, which will in turn pull down all the related TomEE branches. -David
Re: Merging Old and New Websites
If it helps I have an antora setup ([1]) to generate another doc site with most of these features - think only the day/night thing is missing, it uses tags to manage versions - overridable by branches. Side note: when we did the new site we decided to not merge with the old one cause too much stuff was outdated and was causing issues, did you plan to clean it now it has been merged? [1] https://github.com/Talend/component-runtime/tree/master/documentation Le dim. 2 déc. 2018 08:56, Alex The Rocker a écrit : > Hello David, > > Thanks for trying to make TomEE site more readable and accessible! > > I would like to suggest a few more enhancements to make this site as > useful and easy to use as it deserves: > > 1. This site must have navigation links, or better : breadcrumbs > link, in all its pages. > Let me take an example: when I click on the link you gave as an > example: > http://tomee.apache.org/tomee-7.1/examples/application-composer.html, > I arrive on a page which is missing the "context" : I should see that > I am in a documentation page for TomEE version 7.1, subsection > Examples, and I should be allowed to navigate from this page to "The > root of all TomEE docs / The root of all TomEE 71 docs / The root of > all Examples of TomEE 7.1 docs". > Alternative would be to show a TOC (Table Of Contents) next to > all pages, but I personally find TOCs takes to much reading space, > whereas breadcrumbs, if well designed (don't use too long identified > for each "nesting") only take a short space, usual at the top of the > displayed page (but under other navigation elements, like the Search > bar, see #3 below). > > 2. It would be nice to have (not mandatory) a way to switch from > version 7.1 of this page to 7.0 and 8.0. > > 3. A missing feature is a Search bar in the top of all pages, > allowing to search documentation / examples on TomEE site. > > 4. Would it be possible to add a "day / night switch button" ? (see > the Sun/Moon icon at the top right hand side of this site: > https://docs.influxdata.com/telegraf/v1.9/data_formats/template-patterns/ > ), > I love this one, but it's a matter of taste here :) > > 5. (hard) Access to the site from mobiles sucks, requires zooming. > Ideally the styles should implement responsive web design to nicely > fit pages in small displays. > > Disclaimer: I am not a web designer, but I've been participating to > couple of design reviews... > > Kind regards, > Alexandre > > > Le dim. 2 déc. 2018 à 02:41, David Blevins a > écrit : > > > > Alright folks! > > > > Updated site published and with a refreshed CSS that is more readable. > > > > - http://tomee.apache.org/tomee-7.1/examples/application-composer.html > > - http://tomee.apache.org/tomee-8.0/docs/configuring-javamail.html > > > > I'm attempting to get this to a point where we can crowd source some > non-automatable tasks. What I'm imaging we can all do in a divide and > conquer fashion: > > > > - Categorize each document for an intelligent looking index > > - Review each document for formatting issues > > - Convert markdown documents to asciidoc > > - Fix inconsistent h1, h2, h3 etc usage > > - Update branding to "TomEE" from "OpenEJB" > > - Ensure each has a title > > - Check links > > > > To get there I just need to 1) minimally improve the index pages to have > groups and 2) add the jbake headers to all the files > > > > After that everyone can start hacking on docs too. Then I'll move on to > seeing if we can get javadoc generated and published as part of all this. > Then we'll be able to reference them in our docs, which will be very handy > and also provide some motivation to actually write javadoc in the first > place :) > > > > > > -David > > >
Re: Merging Old and New Websites
Hello David, Thanks for trying to make TomEE site more readable and accessible! I would like to suggest a few more enhancements to make this site as useful and easy to use as it deserves: 1. This site must have navigation links, or better : breadcrumbs link, in all its pages. Let me take an example: when I click on the link you gave as an example: http://tomee.apache.org/tomee-7.1/examples/application-composer.html, I arrive on a page which is missing the "context" : I should see that I am in a documentation page for TomEE version 7.1, subsection Examples, and I should be allowed to navigate from this page to "The root of all TomEE docs / The root of all TomEE 71 docs / The root of all Examples of TomEE 7.1 docs". Alternative would be to show a TOC (Table Of Contents) next to all pages, but I personally find TOCs takes to much reading space, whereas breadcrumbs, if well designed (don't use too long identified for each "nesting") only take a short space, usual at the top of the displayed page (but under other navigation elements, like the Search bar, see #3 below). 2. It would be nice to have (not mandatory) a way to switch from version 7.1 of this page to 7.0 and 8.0. 3. A missing feature is a Search bar in the top of all pages, allowing to search documentation / examples on TomEE site. 4. Would it be possible to add a "day / night switch button" ? (see the Sun/Moon icon at the top right hand side of this site: https://docs.influxdata.com/telegraf/v1.9/data_formats/template-patterns/), I love this one, but it's a matter of taste here :) 5. (hard) Access to the site from mobiles sucks, requires zooming. Ideally the styles should implement responsive web design to nicely fit pages in small displays. Disclaimer: I am not a web designer, but I've been participating to couple of design reviews... Kind regards, Alexandre Le dim. 2 déc. 2018 à 02:41, David Blevins a écrit : > > Alright folks! > > Updated site published and with a refreshed CSS that is more readable. > > - http://tomee.apache.org/tomee-7.1/examples/application-composer.html > - http://tomee.apache.org/tomee-8.0/docs/configuring-javamail.html > > I'm attempting to get this to a point where we can crowd source some > non-automatable tasks. What I'm imaging we can all do in a divide and > conquer fashion: > > - Categorize each document for an intelligent looking index > - Review each document for formatting issues > - Convert markdown documents to asciidoc > - Fix inconsistent h1, h2, h3 etc usage > - Update branding to "TomEE" from "OpenEJB" > - Ensure each has a title > - Check links > > To get there I just need to 1) minimally improve the index pages to have > groups and 2) add the jbake headers to all the files > > After that everyone can start hacking on docs too. Then I'll move on to > seeing if we can get javadoc generated and published as part of all this. > Then we'll be able to reference them in our docs, which will be very handy > and also provide some motivation to actually write javadoc in the first place > :) > > > -David >
Re: Merging Old and New Websites
Alright folks! Updated site published and with a refreshed CSS that is more readable. - http://tomee.apache.org/tomee-7.1/examples/application-composer.html - http://tomee.apache.org/tomee-8.0/docs/configuring-javamail.html I'm attempting to get this to a point where we can crowd source some non-automatable tasks. What I'm imaging we can all do in a divide and conquer fashion: - Categorize each document for an intelligent looking index - Review each document for formatting issues - Convert markdown documents to asciidoc - Fix inconsistent h1, h2, h3 etc usage - Update branding to "TomEE" from "OpenEJB" - Ensure each has a title - Check links To get there I just need to 1) minimally improve the index pages to have groups and 2) add the jbake headers to all the files After that everyone can start hacking on docs too. Then I'll move on to seeing if we can get javadoc generated and published as part of all this. Then we'll be able to reference them in our docs, which will be very handy and also provide some motivation to actually write javadoc in the first place :) -David
Re: Merging Old and New Websites
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 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, wo
Re: Merging Old and New Websites
Hi Frankie, My 2 cents here is that we shouldn't wait for the website to be fully migrated. My advice would be, communicate before, during and after your PR. Just yesterday I started to work for the first time in the website: http://tomee-openejb.979440.n4.nabble.com/Improvement-for-Community-section-from-the-website-TOMEE-2300-WIP-tc4685629.html Feel free to contribute with the experiences you mentioned in the previous email. Let us know if you have any further question :) El mié., 28 nov. 2018 a las 8:02, Frankie () escribió: > Sounds great! > As said in > ( > http://tomee-openejb.979440.n4.nabble.com/Feedback-as-newbie-td4685477.html > ) > I would like to share some experiences with my first steps and Jon pointed > to your work on the website. So probably it would be better to wait until > you finished merging. > BTW: Is there a JIRA ticket for the merge so that I can see when it's done? > > > > -- > Sent from: > http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html > -- Atentamente: César Hernández Mendoza.
Re: Merging Old and New Websites
Sounds great! As said in (http://tomee-openejb.979440.n4.nabble.com/Feedback-as-newbie-td4685477.html) I would like to share some experiences with my first steps and Jon pointed to your work on the website. So probably it would be better to wait until you finished merging. BTW: Is there a JIRA ticket for the merge so that I can see when it's done? -- Sent from: http://tomee-openejb.979440.n4.nabble.com/TomEE-Dev-f982480.html
Re: Merging Old and New Websites
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 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
Merging Old and New Websites
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
