Merging Old and New Websites

classic Classic list List threaded Threaded
13 messages Options
Reply | Threaded
Open this post in threaded view
|

Merging Old and New Websites

David Blevins-2
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 [hidden email]: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

Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites

ivanjunckes
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 <[hidden email]>
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 [hidden email]: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
>
>
Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites

Frankie
In reply to this post by David Blevins-2
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
Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites

César Hernández Mendoza
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 (<[hidden email]>)
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.
Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites

David Blevins-2
In reply to this post by David Blevins-2
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 <[hidden email]> 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 [hidden email]: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
>

Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites

David Blevins-2
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

Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites

Alex The Rocker
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 <[hidden email]> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites

Romain Manni-Bucau
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 <[hidden email]> 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 <[hidden email]> 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
> >
>
Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites - Volunteers Needed

David Blevins-2
In reply to this post by David Blevins-2
> On Dec 1, 2018, at 5:41 PM, David Blevins <[hidden email]> 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 [hidden email]: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

Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites

David Blevins-2
In reply to this post by Alex The Rocker
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 <[hidden email]> 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
 
Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites

Alex The Rocker
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 <[hidden email]> 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 <[hidden email]> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites - Volunteers Needed

kmalhi
In reply to this post by David Blevins-2
I will start taking a look at these this week.

On Sun, Dec 2, 2018 at 4:07 AM David Blevins <[hidden email]>
wrote:

> > On Dec 1, 2018, at 5:41 PM, David Blevins <[hidden email]>
> 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 [hidden email]: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
Karan Singh Malhi
Reply | Threaded
Open this post in threaded view
|

Re: Merging Old and New Websites - Volunteers Needed

ivanjunckes
It looks super cool :)

On Mon, Dec 3, 2018 at 4:28 AM Karan Malhi <[hidden email]> wrote:

> I will start taking a look at these this week.
>
> On Sun, Dec 2, 2018 at 4:07 AM David Blevins <[hidden email]>
> wrote:
>
> > > On Dec 1, 2018, at 5:41 PM, David Blevins <[hidden email]>
> > 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 [hidden email]: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
>