You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomee.apache.org by Ivan Junckes Filho <iv...@gmail.com> on 2017/03/10 00:14:07 UTC
TomEE Documentation Suggestion
Hello TomEE developers,
Today TomEE documentation is spread across multiple places, some are not up
to date anymore and some are just really hard to find on the website. It is
easier to find something on google than on http://tomee.apache.org.
I would like to suggest that TomEE uses www.gitbook.com, and we migrate
there the relevant documentation. Updating a website with doc is ok, but I
think it will make the job way easier and will open the gates for
contributors.
All of us here are interested in TomEE documentation to get better and I
think that is a good start, we will not need to keep updating the website,
maintain pages etc we'll just need to use centralized tool.
Please let me know your thoughts.
Please see JNoSQL documentation as a reference:
https://www.gitbook.com/book/jnosql/jnosql-book/details
https://github.com/jnoSQL/jnosql-book
Thank you.
+1? -1?
Re: TomEE Documentation Suggestion
Posted by Romain Manni-Bucau <rm...@gmail.com>.
BTW added a word on the website on the website:
http://tomee.apache.org/community/index.html
Romain Manni-Bucau
@rmannibucau <https://twitter.com/rmannibucau> | Blog
<https://blog-rmannibucau.rhcloud.com> | Old Blog
<http://rmannibucau.wordpress.com> | Github <https://github.com/rmannibucau> |
LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
<https://javaeefactory-rmannibucau.rhcloud.com>
2017-03-10 13:10 GMT+01:00 Romain Manni-Bucau <rm...@gmail.com>:
>
>
> Le 10 mars 2017 13:04, "Ivan Junckes Filho" <iv...@gmail.com> a
> écrit :
>
> I did start writing stuff, but was doing in the html. Seems that I was
> doing wrong because it is unclear how to do it.
>
>
> Clearly not the way, can add a page on the how to help.
>
>
> I consider even this email a contribution btw, discussing possible ways to
> improve it is a good start to better things.
>
> If we don't have an integration and a way to do PR's at the moment I think
> we should fix that. Having it in a personal github account is not ideal.
>
>
> We dont, just proposed it from there.
>
>
>
>
> Even though I respect your opinion I still would like to hear more
> thoughts.
>
> Thank you.
>
>
>
>
>
>
> On Fri, Mar 10, 2017 at 8:44 AM, Romain Manni-Bucau <rmannibucau@gmail.com
> >
> wrote:
>
> > 2017-03-10 12:38 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
> >
> > > As far as I understood JBake is a tool to generate websites (deal with
> > > html, css etc.), what I am proposing is a tool to make the
> documentation
> > > process friendly without caring with html, css, website structure etc.
> > >
> > >
> > Yes but point of using jbake is to be adoc based. You don't care about
> the
> > css, html etc... using it, was one of the criteria.
> >
> >
> > > We don't need to remove JBake from the website, but for documentation,
> we
> > > can use a tool that is proven to work and make it simple.
> > >
> > >
> > Matches jbake definition to be honest.
> >
> >
> > > I don't know where SEO has anything to do with this sorry, but the
> > content
> > > in gitbook is indexed on google if that it what you mean.
> > >
> > >
> > Search Engine Optimization, google integration if you pefer ;)
> >
> >
> > > Well, just my suggestion, I was willing to help on that.
> > >
> > >
> > Did you try contributing on current website - sounds like not? assume we
> > have a github proxy and you can do a PR, do you miss really anything? You
> > can *test* (it isoutdated now but to test it is ok, or if you want i can
> > sync it up for testing purposes) on
> > https://github.com/rmannibucau/site-tomee-ng
> >
> > gitbook gain is mainly about the infra and @ASF we have it provided with
> > standard choices so only the tool and interactions are the remaining
> parts
> > and jbake matches all your criteria for the tool and we can make github
> > integrated so really not seeing what could miss and justify yet another
> > switch.
> >
> >
> > > I would like to hear more thoughts from other developers if possible.
> > >
> > > Thank you.
> > >
> > >
> > >
> > > On Fri, Mar 10, 2017 at 8:10 AM, Romain Manni-Bucau <
> > rmannibucau@gmail.com
> > > >
> > > wrote:
> > >
> > > > 2017-03-10 12:02 GMT+01:00 Ivan Junckes Filho <ivanjunckes@gmail.com
> >:
> > > >
> > > > > Hi guys, thank you for the feedback.
> > > > >
> > > > > What would bring gitbook which would make it better we don't have
> > > > already?
> > > > > 1 - Documentation is a very tough thing to keep up to date, so we
> > don't
> > > > > want to make it hard for people to do it. What I see in gitbook is
> a
> > > very
> > > > > straightforward way to update it and make it organized regardless
> of
> > a
> > > > > website.
> > > > >
> > > >
> > > > Can you go one step further and say how compared to what we have it
> > will
> > > > help (it is the same kind of infra).
> > > >
> > > >
> > > > > 2 - We'll have a tool that is specialized in this, websites need to
> > be
> > > > > redesigned over time and we don't want to be worrying about
> migrating
> > > all
> > > > > the docs like we need to do now, from the old to the new.
> > > > >
> > > >
> > > > JBake as well so once again not sure the gain
> > > >
> > > >
> > > > > 3 - The tool is completely integrated with github, we'll have a
> > project
> > > > > inside the github with folders that we could even separate per
> > > language,
> > > > > would be useful for example if someone with time could go there and
> > > > create
> > > > > a french folder and translate the docs.
> > > > >
> > > >
> > > > Here again we can do it with jbake but have to admit I wonder if this
> > > > someone exist after all the round trips and tries we got on the doc
> so
> > I
> > > > would prefer to take the opposite approad: if someone asks to
> translate
> > > the
> > > > whole website we'll ensure it is setup than setting it up to nothing
> > now.
> > > >
> > > >
> > > > > 4 - We can easily have doc versioning, and make sure from now on
> when
> > > we
> > > > > have a new feature we add it to the doc.
> > > > >
> > > >
> > > > We can but decided to not do it cause majors arent really breaking.
> > > >
> > > >
> > > > > 5 - Authoring is tracked by github itself and can be shared just
> like
> > > > code
> > > > >
> > > >
> > > > Same with svn today and once again no blocker to have a proxy on
> > github.
> > > >
> > > >
> > > > > 6 - Tool is based on .md (markdown) not html
> > > > >
> > > >
> > > > adoc so better no? ;)
> > > >
> > > >
> > > > > 7 - Maybe a straightforward way without learning curve can make
> > people
> > > > > start contributing?
> > > > >
> > > > >
> > > > Learning curve for gitbook ~= jbake I think so not sure.
> > > >
> > > >
> > > > > Imagine this scenario:
> > > > > Let's say I am an application developer that uses TomEE and I
> learned
> > > > > something about it that is not clear in the docs. I don't want to
> > learn
> > > > the
> > > > > whole website thing (structure) etc, I just want to write it and
> send
> > > it
> > > > in
> > > > > an easy manner. This way seems pretty easy in my opinion.
> > > > >
> > > > > We need to make the environment welcoming if we want to improve
> this
> > > > guys!
> > > > >
> > > > > These 2 JavaEE servers have some documentation and they don't keep
> > on a
> > > > > website, they use tools very similar to what I am proposing.
> > > > >
> > > > > Wildfly documentation
> > > > > https://docs.jboss.org/author/display/WFLY10/Documentation
> > > > >
> > > > > Payara documentation
> > > > > https://payara.gitbooks.io/payara-server/content/?
> > > > > hsCtaTracking=8a4f0637-38ea-458c-a66c-6307d6f21923%
> > > > > 7C26bb561b-3f60-4d3b-b64d-06398f00d8e2&__hstc=229474563.
> > > > > 6de427338f64d2f474c236a686036ee9.1489142671622.
> > > > > 1489142671622.1489142671622.1&__hssc=229474563.1.
> > 1489142671623&__hsfp=
> > > > > 2299569188
> > > > >
> > > > > Even though I agree content is more important than tools, I think
> > tools
> > > > > help greatly if we choose the right ones, and they can avoid rework
> > > > which I
> > > > > am sure nobody wants to do if not necessary.
> > > > >
> > > > >
> > > > So globally does your feedback means we need to proxy the website
> > content
> > > > on github and maybe enhance the SEO?
> > > >
> > > >
> > > > >
> > > > > On Fri, Mar 10, 2017 at 5:00 AM, Romain Manni-Bucau <
> > > > rmannibucau@gmail.com
> > > > > >
> > > > > wrote:
> > > > >
> > > > > > 2017-03-10 3:16 GMT+01:00 Thomas Whitmore
> > > <twhitmore@bravurasolutions.
> > > > > com
> > > > > > >:
> > > > > >
> > > > > > > Hi Romain, Ivan,
> > > > > > >
> > > > > > > I agree with Romain and raised the suggestion of improving doc
> a
> > > > month
> > > > > or
> > > > > > > two ago. At the time I offered a few hours to help -- am
> probably
> > > > busy
> > > > > > for
> > > > > > > another month now but do see documentation as an important
> > factor.
> > > > > > >
> > > > > > > My feeling would be that content is more important than tools
> --
> > I
> > > > > would
> > > > > > > see a librarian exercise to collect relevant docs and make them
> > > > > > accessible
> > > > > > > from the new site, as the most relevant. This I believe would
> > give
> > > > the
> > > > > > most
> > > > > > > easy and worthwhile improvement.
> > > > > > >
> > > > > > > My suggestion to move forward:
> > > > > > > - collate docs from "old" openejb.apache.org site; get these
> > > > reviewed
> > > > > > > and edit to remove outdated material.
> > > > > > > - reviewing/ marking of what's outdated & what can be
> > > > corrected
> > > > > > to
> > > > > > > be delegated to appropriate people.
> > > > > > > - make all docs accessible from Documentation areas on new
> > > > > > > tomee.apache.org site;
> > > > > > > - collect prioritized suggestions as to what documentation gaps
> > > > remain.
> > > > > > > - (probably also) for those who found the old site by
> accident,
> > > add
> > > > > > links
> > > > > > > from old site to new Documentation areas on tomee.apache.org
> > site.
> > > > > > >
> > > > > > > This should make it possible to cheaply & easily gather all
> > useful
> > > > > > > material from existing docs, consolidate the docs, and produce
> a
> > > > > > shortlist
> > > > > > > of doc to fill in.
> > > > > > >
> > > > > > > However I did look at Gitbook (www.gitbook.com) and it looks
> > quite
> > > > > > > interesting. How is the website/ documentation maintained at
> the
> > > > > moment?
> > > > > > > Would a tool like Gitbook enable better shared authoring or
> make
> > > > > content
> > > > > > > writing easier (eg rich text editor, not raw HTML)? These are
> > > > > interesting
> > > > > > > questions. It might also be possible to use gitbook to share
> > > writing,
> > > > > > then
> > > > > > > upload resulting HTML to an existing website repo if that's how
> > > > website
> > > > > > is
> > > > > > > maintained at the moment. See https://docs.duckduckhack.com/
> for
> > > an
> > > > > > > example of Gitbook-produced docs.
> > > > > > >
> > > > > > >
> > > > > > we use a jbake site (
> > > > > > http://svn.apache.org/repos/asf/tomee/site/trunk/
> > > > > > generators/site-tomee-ng/src/main/jbake/
> > > > > > - development with tomee itself ;)) the we just sync with site
> > > content
> > > > > > http://svn.apache.org/repos/asf/tomee/site/trunk/content/ and
> push
> > > > > through
> > > > > > ASF mecanism ("CMS") which is basically a svn deployed on a
> click.
> > > Nice
> > > > > > thing of that tooling is the autostaging mode so you have a site
> > > > preview
> > > > > > before the prod one.
> > > > > >
> > > > > > So concretely we are in managed and public so already shareable.
> If
> > > > > github
> > > > > > is better we can sync with github like tomee itself, that's a
> > detail.
> > > > And
> > > > > > we are adoc so github would just bring another structure but if
> you
> > > > check
> > > > > > we already have one. The search is interesting and I guess we'll
> > need
> > > > to
> > > > > > add a kind of client search at build time or just use google.
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > > I would suggest that TomEE as a project is technically nice,
> but
> > > > > > > documentation may be holding it back. People on the mailing
> list
> > > are
> > > > > > great
> > > > > > > & very helpful and willing to answer questions, but I would
> > believe
> > > > > that
> > > > > > > providing this material as findable written documentation on
> the
> > > > > current
> > > > > > > (new) website is important, as documentation is one of the #1
> > > things
> > > > > > people
> > > > > > > consider when considering a platform.
> > > > > > >
> > > > > > >
> > > > > > > Regards,
> > > > > > > Thomas
> > > > > > >
> > > > > > > -----Original Message-----
> > > > > > > From: Romain Manni-Bucau [mailto:rmannibucau@gmail.com]
> > > > > > > Sent: Friday, 10 March 2017 1:37 PM
> > > > > > > To: dev@tomee.apache.org
> > > > > > > Subject: Re: TomEE Documentation Suggestion
> > > > > > >
> > > > > > > Hi Ivan,
> > > > > > >
> > > > > > > we just revamped the website with a new structure, I know it is
> > not
> > > > > > > perfect but a step to something better. Tooling is also way
> > easier
> > > > now
> > > > > to
> > > > > > > get started with. So question is: what would bring gitbook
> which
> > > > would
> > > > > > make
> > > > > > > it better we don't have already? If github we can ask infra to
> > > proxy
> > > > > our
> > > > > > > site repo on ASF github org.
> > > > > > >
> > > > > > >
> > > > > > > Romain Manni-Bucau
> > > > > > > @rmannibucau <https://twitter.com/rmannibucau> | Blog <
> > > > > > > https://blog-rmannibucau.rhcloud.com> | Old Blog <
> > > > > > > http://rmannibucau.wordpress.com> | Github <
> https://github.com/
> > > > > > rmannibucau>
> > > > > > > | LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE
> > > > Factory
> > > > > <
> > > > > > > https://javaeefactory-rmannibucau.rhcloud.com>
> > > > > > >
> > > > > > > 2017-03-10 1:14 GMT+01:00 Ivan Junckes Filho <
> > > ivanjunckes@gmail.com
> > > > >:
> > > > > > >
> > > > > > > > Hello TomEE developers,
> > > > > > > >
> > > > > > > > Today TomEE documentation is spread across multiple places,
> > some
> > > > are
> > > > > > > > not up to date anymore and some are just really hard to find
> on
> > > the
> > > > > > > > website. It is easier to find something on google than on
> > > > > > > http://tomee.apache.org.
> > > > > > > >
> > > > > > > > I would like to suggest that TomEE uses www.gitbook.com, and
> > we
> > > > > > > > migrate there the relevant documentation. Updating a website
> > with
> > > > doc
> > > > > > > > is ok, but I think it will make the job way easier and will
> > open
> > > > the
> > > > > > > > gates for contributors.
> > > > > > >
> > > > > > > ____________________________________________________________
> > > > __________
> > > > > > > This email has been scanned by the Symantec Email
> Security.cloud
> > > > > service.
> > > > > > > For more information please visit http://www.symanteccloud.com
> > > > > > > ____________________________________________________________
> > > > __________
> > > > > > >
> > > > > >
> > > > >
> > > >
> > >
> >
>
>
>
Re: TomEE Documentation Suggestion
Posted by Romain Manni-Bucau <rm...@gmail.com>.
Le 10 mars 2017 13:04, "Ivan Junckes Filho" <iv...@gmail.com> a
écrit :
I did start writing stuff, but was doing in the html. Seems that I was
doing wrong because it is unclear how to do it.
Clearly not the way, can add a page on the how to help.
I consider even this email a contribution btw, discussing possible ways to
improve it is a good start to better things.
If we don't have an integration and a way to do PR's at the moment I think
we should fix that. Having it in a personal github account is not ideal.
We dont, just proposed it from there.
Even though I respect your opinion I still would like to hear more thoughts.
Thank you.
On Fri, Mar 10, 2017 at 8:44 AM, Romain Manni-Bucau <rm...@gmail.com>
wrote:
> 2017-03-10 12:38 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
>
> > As far as I understood JBake is a tool to generate websites (deal with
> > html, css etc.), what I am proposing is a tool to make the documentation
> > process friendly without caring with html, css, website structure etc.
> >
> >
> Yes but point of using jbake is to be adoc based. You don't care about the
> css, html etc... using it, was one of the criteria.
>
>
> > We don't need to remove JBake from the website, but for documentation,
we
> > can use a tool that is proven to work and make it simple.
> >
> >
> Matches jbake definition to be honest.
>
>
> > I don't know where SEO has anything to do with this sorry, but the
> content
> > in gitbook is indexed on google if that it what you mean.
> >
> >
> Search Engine Optimization, google integration if you pefer ;)
>
>
> > Well, just my suggestion, I was willing to help on that.
> >
> >
> Did you try contributing on current website - sounds like not? assume we
> have a github proxy and you can do a PR, do you miss really anything? You
> can *test* (it isoutdated now but to test it is ok, or if you want i can
> sync it up for testing purposes) on
> https://github.com/rmannibucau/site-tomee-ng
>
> gitbook gain is mainly about the infra and @ASF we have it provided with
> standard choices so only the tool and interactions are the remaining parts
> and jbake matches all your criteria for the tool and we can make github
> integrated so really not seeing what could miss and justify yet another
> switch.
>
>
> > I would like to hear more thoughts from other developers if possible.
> >
> > Thank you.
> >
> >
> >
> > On Fri, Mar 10, 2017 at 8:10 AM, Romain Manni-Bucau <
> rmannibucau@gmail.com
> > >
> > wrote:
> >
> > > 2017-03-10 12:02 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
> > >
> > > > Hi guys, thank you for the feedback.
> > > >
> > > > What would bring gitbook which would make it better we don't have
> > > already?
> > > > 1 - Documentation is a very tough thing to keep up to date, so we
> don't
> > > > want to make it hard for people to do it. What I see in gitbook is a
> > very
> > > > straightforward way to update it and make it organized regardless of
> a
> > > > website.
> > > >
> > >
> > > Can you go one step further and say how compared to what we have it
> will
> > > help (it is the same kind of infra).
> > >
> > >
> > > > 2 - We'll have a tool that is specialized in this, websites need to
> be
> > > > redesigned over time and we don't want to be worrying about
migrating
> > all
> > > > the docs like we need to do now, from the old to the new.
> > > >
> > >
> > > JBake as well so once again not sure the gain
> > >
> > >
> > > > 3 - The tool is completely integrated with github, we'll have a
> project
> > > > inside the github with folders that we could even separate per
> > language,
> > > > would be useful for example if someone with time could go there and
> > > create
> > > > a french folder and translate the docs.
> > > >
> > >
> > > Here again we can do it with jbake but have to admit I wonder if this
> > > someone exist after all the round trips and tries we got on the doc so
> I
> > > would prefer to take the opposite approad: if someone asks to
translate
> > the
> > > whole website we'll ensure it is setup than setting it up to nothing
> now.
> > >
> > >
> > > > 4 - We can easily have doc versioning, and make sure from now on
when
> > we
> > > > have a new feature we add it to the doc.
> > > >
> > >
> > > We can but decided to not do it cause majors arent really breaking.
> > >
> > >
> > > > 5 - Authoring is tracked by github itself and can be shared just
like
> > > code
> > > >
> > >
> > > Same with svn today and once again no blocker to have a proxy on
> github.
> > >
> > >
> > > > 6 - Tool is based on .md (markdown) not html
> > > >
> > >
> > > adoc so better no? ;)
> > >
> > >
> > > > 7 - Maybe a straightforward way without learning curve can make
> people
> > > > start contributing?
> > > >
> > > >
> > > Learning curve for gitbook ~= jbake I think so not sure.
> > >
> > >
> > > > Imagine this scenario:
> > > > Let's say I am an application developer that uses TomEE and I
learned
> > > > something about it that is not clear in the docs. I don't want to
> learn
> > > the
> > > > whole website thing (structure) etc, I just want to write it and
send
> > it
> > > in
> > > > an easy manner. This way seems pretty easy in my opinion.
> > > >
> > > > We need to make the environment welcoming if we want to improve this
> > > guys!
> > > >
> > > > These 2 JavaEE servers have some documentation and they don't keep
> on a
> > > > website, they use tools very similar to what I am proposing.
> > > >
> > > > Wildfly documentation
> > > > https://docs.jboss.org/author/display/WFLY10/Documentation
> > > >
> > > > Payara documentation
> > > > https://payara.gitbooks.io/payara-server/content/?
> > > > hsCtaTracking=8a4f0637-38ea-458c-a66c-6307d6f21923%
> > > > 7C26bb561b-3f60-4d3b-b64d-06398f00d8e2&__hstc=229474563.
> > > > 6de427338f64d2f474c236a686036ee9.1489142671622.
> > > > 1489142671622.1489142671622.1&__hssc=229474563.1.
> 1489142671623&__hsfp=
> > > > 2299569188
> > > >
> > > > Even though I agree content is more important than tools, I think
> tools
> > > > help greatly if we choose the right ones, and they can avoid rework
> > > which I
> > > > am sure nobody wants to do if not necessary.
> > > >
> > > >
> > > So globally does your feedback means we need to proxy the website
> content
> > > on github and maybe enhance the SEO?
> > >
> > >
> > > >
> > > > On Fri, Mar 10, 2017 at 5:00 AM, Romain Manni-Bucau <
> > > rmannibucau@gmail.com
> > > > >
> > > > wrote:
> > > >
> > > > > 2017-03-10 3:16 GMT+01:00 Thomas Whitmore
> > <twhitmore@bravurasolutions.
> > > > com
> > > > > >:
> > > > >
> > > > > > Hi Romain, Ivan,
> > > > > >
> > > > > > I agree with Romain and raised the suggestion of improving doc a
> > > month
> > > > or
> > > > > > two ago. At the time I offered a few hours to help -- am
probably
> > > busy
> > > > > for
> > > > > > another month now but do see documentation as an important
> factor.
> > > > > >
> > > > > > My feeling would be that content is more important than tools --
> I
> > > > would
> > > > > > see a librarian exercise to collect relevant docs and make them
> > > > > accessible
> > > > > > from the new site, as the most relevant. This I believe would
> give
> > > the
> > > > > most
> > > > > > easy and worthwhile improvement.
> > > > > >
> > > > > > My suggestion to move forward:
> > > > > > - collate docs from "old" openejb.apache.org site; get these
> > > reviewed
> > > > > > and edit to remove outdated material.
> > > > > > - reviewing/ marking of what's outdated & what can be
> > > corrected
> > > > > to
> > > > > > be delegated to appropriate people.
> > > > > > - make all docs accessible from Documentation areas on new
> > > > > > tomee.apache.org site;
> > > > > > - collect prioritized suggestions as to what documentation gaps
> > > remain.
> > > > > > - (probably also) for those who found the old site by accident,
> > add
> > > > > links
> > > > > > from old site to new Documentation areas on tomee.apache.org
> site.
> > > > > >
> > > > > > This should make it possible to cheaply & easily gather all
> useful
> > > > > > material from existing docs, consolidate the docs, and produce a
> > > > > shortlist
> > > > > > of doc to fill in.
> > > > > >
> > > > > > However I did look at Gitbook (www.gitbook.com) and it looks
> quite
> > > > > > interesting. How is the website/ documentation maintained at the
> > > > moment?
> > > > > > Would a tool like Gitbook enable better shared authoring or make
> > > > content
> > > > > > writing easier (eg rich text editor, not raw HTML)? These are
> > > > interesting
> > > > > > questions. It might also be possible to use gitbook to share
> > writing,
> > > > > then
> > > > > > upload resulting HTML to an existing website repo if that's how
> > > website
> > > > > is
> > > > > > maintained at the moment. See https://docs.duckduckhack.com/ for
> > an
> > > > > > example of Gitbook-produced docs.
> > > > > >
> > > > > >
> > > > > we use a jbake site (
> > > > > http://svn.apache.org/repos/asf/tomee/site/trunk/
> > > > > generators/site-tomee-ng/src/main/jbake/
> > > > > - development with tomee itself ;)) the we just sync with site
> > content
> > > > > http://svn.apache.org/repos/asf/tomee/site/trunk/content/ and push
> > > > through
> > > > > ASF mecanism ("CMS") which is basically a svn deployed on a click.
> > Nice
> > > > > thing of that tooling is the autostaging mode so you have a site
> > > preview
> > > > > before the prod one.
> > > > >
> > > > > So concretely we are in managed and public so already shareable.
If
> > > > github
> > > > > is better we can sync with github like tomee itself, that's a
> detail.
> > > And
> > > > > we are adoc so github would just bring another structure but if
you
> > > check
> > > > > we already have one. The search is interesting and I guess we'll
> need
> > > to
> > > > > add a kind of client search at build time or just use google.
> > > > >
> > > > >
> > > > >
> > > > >
> > > > > > I would suggest that TomEE as a project is technically nice, but
> > > > > > documentation may be holding it back. People on the mailing list
> > are
> > > > > great
> > > > > > & very helpful and willing to answer questions, but I would
> believe
> > > > that
> > > > > > providing this material as findable written documentation on the
> > > > current
> > > > > > (new) website is important, as documentation is one of the #1
> > things
> > > > > people
> > > > > > consider when considering a platform.
> > > > > >
> > > > > >
> > > > > > Regards,
> > > > > > Thomas
> > > > > >
> > > > > > -----Original Message-----
> > > > > > From: Romain Manni-Bucau [mailto:rmannibucau@gmail.com]
> > > > > > Sent: Friday, 10 March 2017 1:37 PM
> > > > > > To: dev@tomee.apache.org
> > > > > > Subject: Re: TomEE Documentation Suggestion
> > > > > >
> > > > > > Hi Ivan,
> > > > > >
> > > > > > we just revamped the website with a new structure, I know it is
> not
> > > > > > perfect but a step to something better. Tooling is also way
> easier
> > > now
> > > > to
> > > > > > get started with. So question is: what would bring gitbook which
> > > would
> > > > > make
> > > > > > it better we don't have already? If github we can ask infra to
> > proxy
> > > > our
> > > > > > site repo on ASF github org.
> > > > > >
> > > > > >
> > > > > > Romain Manni-Bucau
> > > > > > @rmannibucau <https://twitter.com/rmannibucau> | Blog <
> > > > > > https://blog-rmannibucau.rhcloud.com> | Old Blog <
> > > > > > http://rmannibucau.wordpress.com> | Github <https://github.com/
> > > > > rmannibucau>
> > > > > > | LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE
> > > Factory
> > > > <
> > > > > > https://javaeefactory-rmannibucau.rhcloud.com>
> > > > > >
> > > > > > 2017-03-10 1:14 GMT+01:00 Ivan Junckes Filho <
> > ivanjunckes@gmail.com
> > > >:
> > > > > >
> > > > > > > Hello TomEE developers,
> > > > > > >
> > > > > > > Today TomEE documentation is spread across multiple places,
> some
> > > are
> > > > > > > not up to date anymore and some are just really hard to find
on
> > the
> > > > > > > website. It is easier to find something on google than on
> > > > > > http://tomee.apache.org.
> > > > > > >
> > > > > > > I would like to suggest that TomEE uses www.gitbook.com, and
> we
> > > > > > > migrate there the relevant documentation. Updating a website
> with
> > > doc
> > > > > > > is ok, but I think it will make the job way easier and will
> open
> > > the
> > > > > > > gates for contributors.
> > > > > >
> > > > > > ____________________________________________________________
> > > __________
> > > > > > This email has been scanned by the Symantec Email Security.cloud
> > > > service.
> > > > > > For more information please visit http://www.symanteccloud.com
> > > > > > ____________________________________________________________
> > > __________
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: TomEE Documentation Suggestion
Posted by Ivan Junckes Filho <iv...@gmail.com>.
I did start writing stuff, but was doing in the html. Seems that I was
doing wrong because it is unclear how to do it.
I consider even this email a contribution btw, discussing possible ways to
improve it is a good start to better things.
If we don't have an integration and a way to do PR's at the moment I think
we should fix that. Having it in a personal github account is not ideal.
Even though I respect your opinion I still would like to hear more thoughts.
Thank you.
On Fri, Mar 10, 2017 at 8:44 AM, Romain Manni-Bucau <rm...@gmail.com>
wrote:
> 2017-03-10 12:38 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
>
> > As far as I understood JBake is a tool to generate websites (deal with
> > html, css etc.), what I am proposing is a tool to make the documentation
> > process friendly without caring with html, css, website structure etc.
> >
> >
> Yes but point of using jbake is to be adoc based. You don't care about the
> css, html etc... using it, was one of the criteria.
>
>
> > We don't need to remove JBake from the website, but for documentation, we
> > can use a tool that is proven to work and make it simple.
> >
> >
> Matches jbake definition to be honest.
>
>
> > I don't know where SEO has anything to do with this sorry, but the
> content
> > in gitbook is indexed on google if that it what you mean.
> >
> >
> Search Engine Optimization, google integration if you pefer ;)
>
>
> > Well, just my suggestion, I was willing to help on that.
> >
> >
> Did you try contributing on current website - sounds like not? assume we
> have a github proxy and you can do a PR, do you miss really anything? You
> can *test* (it isoutdated now but to test it is ok, or if you want i can
> sync it up for testing purposes) on
> https://github.com/rmannibucau/site-tomee-ng
>
> gitbook gain is mainly about the infra and @ASF we have it provided with
> standard choices so only the tool and interactions are the remaining parts
> and jbake matches all your criteria for the tool and we can make github
> integrated so really not seeing what could miss and justify yet another
> switch.
>
>
> > I would like to hear more thoughts from other developers if possible.
> >
> > Thank you.
> >
> >
> >
> > On Fri, Mar 10, 2017 at 8:10 AM, Romain Manni-Bucau <
> rmannibucau@gmail.com
> > >
> > wrote:
> >
> > > 2017-03-10 12:02 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
> > >
> > > > Hi guys, thank you for the feedback.
> > > >
> > > > What would bring gitbook which would make it better we don't have
> > > already?
> > > > 1 - Documentation is a very tough thing to keep up to date, so we
> don't
> > > > want to make it hard for people to do it. What I see in gitbook is a
> > very
> > > > straightforward way to update it and make it organized regardless of
> a
> > > > website.
> > > >
> > >
> > > Can you go one step further and say how compared to what we have it
> will
> > > help (it is the same kind of infra).
> > >
> > >
> > > > 2 - We'll have a tool that is specialized in this, websites need to
> be
> > > > redesigned over time and we don't want to be worrying about migrating
> > all
> > > > the docs like we need to do now, from the old to the new.
> > > >
> > >
> > > JBake as well so once again not sure the gain
> > >
> > >
> > > > 3 - The tool is completely integrated with github, we'll have a
> project
> > > > inside the github with folders that we could even separate per
> > language,
> > > > would be useful for example if someone with time could go there and
> > > create
> > > > a french folder and translate the docs.
> > > >
> > >
> > > Here again we can do it with jbake but have to admit I wonder if this
> > > someone exist after all the round trips and tries we got on the doc so
> I
> > > would prefer to take the opposite approad: if someone asks to translate
> > the
> > > whole website we'll ensure it is setup than setting it up to nothing
> now.
> > >
> > >
> > > > 4 - We can easily have doc versioning, and make sure from now on when
> > we
> > > > have a new feature we add it to the doc.
> > > >
> > >
> > > We can but decided to not do it cause majors arent really breaking.
> > >
> > >
> > > > 5 - Authoring is tracked by github itself and can be shared just like
> > > code
> > > >
> > >
> > > Same with svn today and once again no blocker to have a proxy on
> github.
> > >
> > >
> > > > 6 - Tool is based on .md (markdown) not html
> > > >
> > >
> > > adoc so better no? ;)
> > >
> > >
> > > > 7 - Maybe a straightforward way without learning curve can make
> people
> > > > start contributing?
> > > >
> > > >
> > > Learning curve for gitbook ~= jbake I think so not sure.
> > >
> > >
> > > > Imagine this scenario:
> > > > Let's say I am an application developer that uses TomEE and I learned
> > > > something about it that is not clear in the docs. I don't want to
> learn
> > > the
> > > > whole website thing (structure) etc, I just want to write it and send
> > it
> > > in
> > > > an easy manner. This way seems pretty easy in my opinion.
> > > >
> > > > We need to make the environment welcoming if we want to improve this
> > > guys!
> > > >
> > > > These 2 JavaEE servers have some documentation and they don't keep
> on a
> > > > website, they use tools very similar to what I am proposing.
> > > >
> > > > Wildfly documentation
> > > > https://docs.jboss.org/author/display/WFLY10/Documentation
> > > >
> > > > Payara documentation
> > > > https://payara.gitbooks.io/payara-server/content/?
> > > > hsCtaTracking=8a4f0637-38ea-458c-a66c-6307d6f21923%
> > > > 7C26bb561b-3f60-4d3b-b64d-06398f00d8e2&__hstc=229474563.
> > > > 6de427338f64d2f474c236a686036ee9.1489142671622.
> > > > 1489142671622.1489142671622.1&__hssc=229474563.1.
> 1489142671623&__hsfp=
> > > > 2299569188
> > > >
> > > > Even though I agree content is more important than tools, I think
> tools
> > > > help greatly if we choose the right ones, and they can avoid rework
> > > which I
> > > > am sure nobody wants to do if not necessary.
> > > >
> > > >
> > > So globally does your feedback means we need to proxy the website
> content
> > > on github and maybe enhance the SEO?
> > >
> > >
> > > >
> > > > On Fri, Mar 10, 2017 at 5:00 AM, Romain Manni-Bucau <
> > > rmannibucau@gmail.com
> > > > >
> > > > wrote:
> > > >
> > > > > 2017-03-10 3:16 GMT+01:00 Thomas Whitmore
> > <twhitmore@bravurasolutions.
> > > > com
> > > > > >:
> > > > >
> > > > > > Hi Romain, Ivan,
> > > > > >
> > > > > > I agree with Romain and raised the suggestion of improving doc a
> > > month
> > > > or
> > > > > > two ago. At the time I offered a few hours to help -- am probably
> > > busy
> > > > > for
> > > > > > another month now but do see documentation as an important
> factor.
> > > > > >
> > > > > > My feeling would be that content is more important than tools --
> I
> > > > would
> > > > > > see a librarian exercise to collect relevant docs and make them
> > > > > accessible
> > > > > > from the new site, as the most relevant. This I believe would
> give
> > > the
> > > > > most
> > > > > > easy and worthwhile improvement.
> > > > > >
> > > > > > My suggestion to move forward:
> > > > > > - collate docs from "old" openejb.apache.org site; get these
> > > reviewed
> > > > > > and edit to remove outdated material.
> > > > > > - reviewing/ marking of what's outdated & what can be
> > > corrected
> > > > > to
> > > > > > be delegated to appropriate people.
> > > > > > - make all docs accessible from Documentation areas on new
> > > > > > tomee.apache.org site;
> > > > > > - collect prioritized suggestions as to what documentation gaps
> > > remain.
> > > > > > - (probably also) for those who found the old site by accident,
> > add
> > > > > links
> > > > > > from old site to new Documentation areas on tomee.apache.org
> site.
> > > > > >
> > > > > > This should make it possible to cheaply & easily gather all
> useful
> > > > > > material from existing docs, consolidate the docs, and produce a
> > > > > shortlist
> > > > > > of doc to fill in.
> > > > > >
> > > > > > However I did look at Gitbook (www.gitbook.com) and it looks
> quite
> > > > > > interesting. How is the website/ documentation maintained at the
> > > > moment?
> > > > > > Would a tool like Gitbook enable better shared authoring or make
> > > > content
> > > > > > writing easier (eg rich text editor, not raw HTML)? These are
> > > > interesting
> > > > > > questions. It might also be possible to use gitbook to share
> > writing,
> > > > > then
> > > > > > upload resulting HTML to an existing website repo if that's how
> > > website
> > > > > is
> > > > > > maintained at the moment. See https://docs.duckduckhack.com/ for
> > an
> > > > > > example of Gitbook-produced docs.
> > > > > >
> > > > > >
> > > > > we use a jbake site (
> > > > > http://svn.apache.org/repos/asf/tomee/site/trunk/
> > > > > generators/site-tomee-ng/src/main/jbake/
> > > > > - development with tomee itself ;)) the we just sync with site
> > content
> > > > > http://svn.apache.org/repos/asf/tomee/site/trunk/content/ and push
> > > > through
> > > > > ASF mecanism ("CMS") which is basically a svn deployed on a click.
> > Nice
> > > > > thing of that tooling is the autostaging mode so you have a site
> > > preview
> > > > > before the prod one.
> > > > >
> > > > > So concretely we are in managed and public so already shareable. If
> > > > github
> > > > > is better we can sync with github like tomee itself, that's a
> detail.
> > > And
> > > > > we are adoc so github would just bring another structure but if you
> > > check
> > > > > we already have one. The search is interesting and I guess we'll
> need
> > > to
> > > > > add a kind of client search at build time or just use google.
> > > > >
> > > > >
> > > > >
> > > > >
> > > > > > I would suggest that TomEE as a project is technically nice, but
> > > > > > documentation may be holding it back. People on the mailing list
> > are
> > > > > great
> > > > > > & very helpful and willing to answer questions, but I would
> believe
> > > > that
> > > > > > providing this material as findable written documentation on the
> > > > current
> > > > > > (new) website is important, as documentation is one of the #1
> > things
> > > > > people
> > > > > > consider when considering a platform.
> > > > > >
> > > > > >
> > > > > > Regards,
> > > > > > Thomas
> > > > > >
> > > > > > -----Original Message-----
> > > > > > From: Romain Manni-Bucau [mailto:rmannibucau@gmail.com]
> > > > > > Sent: Friday, 10 March 2017 1:37 PM
> > > > > > To: dev@tomee.apache.org
> > > > > > Subject: Re: TomEE Documentation Suggestion
> > > > > >
> > > > > > Hi Ivan,
> > > > > >
> > > > > > we just revamped the website with a new structure, I know it is
> not
> > > > > > perfect but a step to something better. Tooling is also way
> easier
> > > now
> > > > to
> > > > > > get started with. So question is: what would bring gitbook which
> > > would
> > > > > make
> > > > > > it better we don't have already? If github we can ask infra to
> > proxy
> > > > our
> > > > > > site repo on ASF github org.
> > > > > >
> > > > > >
> > > > > > Romain Manni-Bucau
> > > > > > @rmannibucau <https://twitter.com/rmannibucau> | Blog <
> > > > > > https://blog-rmannibucau.rhcloud.com> | Old Blog <
> > > > > > http://rmannibucau.wordpress.com> | Github <https://github.com/
> > > > > rmannibucau>
> > > > > > | LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE
> > > Factory
> > > > <
> > > > > > https://javaeefactory-rmannibucau.rhcloud.com>
> > > > > >
> > > > > > 2017-03-10 1:14 GMT+01:00 Ivan Junckes Filho <
> > ivanjunckes@gmail.com
> > > >:
> > > > > >
> > > > > > > Hello TomEE developers,
> > > > > > >
> > > > > > > Today TomEE documentation is spread across multiple places,
> some
> > > are
> > > > > > > not up to date anymore and some are just really hard to find on
> > the
> > > > > > > website. It is easier to find something on google than on
> > > > > > http://tomee.apache.org.
> > > > > > >
> > > > > > > I would like to suggest that TomEE uses www.gitbook.com, and
> we
> > > > > > > migrate there the relevant documentation. Updating a website
> with
> > > doc
> > > > > > > is ok, but I think it will make the job way easier and will
> open
> > > the
> > > > > > > gates for contributors.
> > > > > >
> > > > > > ____________________________________________________________
> > > __________
> > > > > > This email has been scanned by the Symantec Email Security.cloud
> > > > service.
> > > > > > For more information please visit http://www.symanteccloud.com
> > > > > > ____________________________________________________________
> > > __________
> > > > > >
> > > > >
> > > >
> > >
> >
>
Re: TomEE Documentation Suggestion
Posted by Romain Manni-Bucau <rm...@gmail.com>.
2017-03-10 12:38 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
> As far as I understood JBake is a tool to generate websites (deal with
> html, css etc.), what I am proposing is a tool to make the documentation
> process friendly without caring with html, css, website structure etc.
>
>
Yes but point of using jbake is to be adoc based. You don't care about the
css, html etc... using it, was one of the criteria.
> We don't need to remove JBake from the website, but for documentation, we
> can use a tool that is proven to work and make it simple.
>
>
Matches jbake definition to be honest.
> I don't know where SEO has anything to do with this sorry, but the content
> in gitbook is indexed on google if that it what you mean.
>
>
Search Engine Optimization, google integration if you pefer ;)
> Well, just my suggestion, I was willing to help on that.
>
>
Did you try contributing on current website - sounds like not? assume we
have a github proxy and you can do a PR, do you miss really anything? You
can *test* (it isoutdated now but to test it is ok, or if you want i can
sync it up for testing purposes) on
https://github.com/rmannibucau/site-tomee-ng
gitbook gain is mainly about the infra and @ASF we have it provided with
standard choices so only the tool and interactions are the remaining parts
and jbake matches all your criteria for the tool and we can make github
integrated so really not seeing what could miss and justify yet another
switch.
> I would like to hear more thoughts from other developers if possible.
>
> Thank you.
>
>
>
> On Fri, Mar 10, 2017 at 8:10 AM, Romain Manni-Bucau <rmannibucau@gmail.com
> >
> wrote:
>
> > 2017-03-10 12:02 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
> >
> > > Hi guys, thank you for the feedback.
> > >
> > > What would bring gitbook which would make it better we don't have
> > already?
> > > 1 - Documentation is a very tough thing to keep up to date, so we don't
> > > want to make it hard for people to do it. What I see in gitbook is a
> very
> > > straightforward way to update it and make it organized regardless of a
> > > website.
> > >
> >
> > Can you go one step further and say how compared to what we have it will
> > help (it is the same kind of infra).
> >
> >
> > > 2 - We'll have a tool that is specialized in this, websites need to be
> > > redesigned over time and we don't want to be worrying about migrating
> all
> > > the docs like we need to do now, from the old to the new.
> > >
> >
> > JBake as well so once again not sure the gain
> >
> >
> > > 3 - The tool is completely integrated with github, we'll have a project
> > > inside the github with folders that we could even separate per
> language,
> > > would be useful for example if someone with time could go there and
> > create
> > > a french folder and translate the docs.
> > >
> >
> > Here again we can do it with jbake but have to admit I wonder if this
> > someone exist after all the round trips and tries we got on the doc so I
> > would prefer to take the opposite approad: if someone asks to translate
> the
> > whole website we'll ensure it is setup than setting it up to nothing now.
> >
> >
> > > 4 - We can easily have doc versioning, and make sure from now on when
> we
> > > have a new feature we add it to the doc.
> > >
> >
> > We can but decided to not do it cause majors arent really breaking.
> >
> >
> > > 5 - Authoring is tracked by github itself and can be shared just like
> > code
> > >
> >
> > Same with svn today and once again no blocker to have a proxy on github.
> >
> >
> > > 6 - Tool is based on .md (markdown) not html
> > >
> >
> > adoc so better no? ;)
> >
> >
> > > 7 - Maybe a straightforward way without learning curve can make people
> > > start contributing?
> > >
> > >
> > Learning curve for gitbook ~= jbake I think so not sure.
> >
> >
> > > Imagine this scenario:
> > > Let's say I am an application developer that uses TomEE and I learned
> > > something about it that is not clear in the docs. I don't want to learn
> > the
> > > whole website thing (structure) etc, I just want to write it and send
> it
> > in
> > > an easy manner. This way seems pretty easy in my opinion.
> > >
> > > We need to make the environment welcoming if we want to improve this
> > guys!
> > >
> > > These 2 JavaEE servers have some documentation and they don't keep on a
> > > website, they use tools very similar to what I am proposing.
> > >
> > > Wildfly documentation
> > > https://docs.jboss.org/author/display/WFLY10/Documentation
> > >
> > > Payara documentation
> > > https://payara.gitbooks.io/payara-server/content/?
> > > hsCtaTracking=8a4f0637-38ea-458c-a66c-6307d6f21923%
> > > 7C26bb561b-3f60-4d3b-b64d-06398f00d8e2&__hstc=229474563.
> > > 6de427338f64d2f474c236a686036ee9.1489142671622.
> > > 1489142671622.1489142671622.1&__hssc=229474563.1.1489142671623&__hsfp=
> > > 2299569188
> > >
> > > Even though I agree content is more important than tools, I think tools
> > > help greatly if we choose the right ones, and they can avoid rework
> > which I
> > > am sure nobody wants to do if not necessary.
> > >
> > >
> > So globally does your feedback means we need to proxy the website content
> > on github and maybe enhance the SEO?
> >
> >
> > >
> > > On Fri, Mar 10, 2017 at 5:00 AM, Romain Manni-Bucau <
> > rmannibucau@gmail.com
> > > >
> > > wrote:
> > >
> > > > 2017-03-10 3:16 GMT+01:00 Thomas Whitmore
> <twhitmore@bravurasolutions.
> > > com
> > > > >:
> > > >
> > > > > Hi Romain, Ivan,
> > > > >
> > > > > I agree with Romain and raised the suggestion of improving doc a
> > month
> > > or
> > > > > two ago. At the time I offered a few hours to help -- am probably
> > busy
> > > > for
> > > > > another month now but do see documentation as an important factor.
> > > > >
> > > > > My feeling would be that content is more important than tools -- I
> > > would
> > > > > see a librarian exercise to collect relevant docs and make them
> > > > accessible
> > > > > from the new site, as the most relevant. This I believe would give
> > the
> > > > most
> > > > > easy and worthwhile improvement.
> > > > >
> > > > > My suggestion to move forward:
> > > > > - collate docs from "old" openejb.apache.org site; get these
> > reviewed
> > > > > and edit to remove outdated material.
> > > > > - reviewing/ marking of what's outdated & what can be
> > corrected
> > > > to
> > > > > be delegated to appropriate people.
> > > > > - make all docs accessible from Documentation areas on new
> > > > > tomee.apache.org site;
> > > > > - collect prioritized suggestions as to what documentation gaps
> > remain.
> > > > > - (probably also) for those who found the old site by accident,
> add
> > > > links
> > > > > from old site to new Documentation areas on tomee.apache.org site.
> > > > >
> > > > > This should make it possible to cheaply & easily gather all useful
> > > > > material from existing docs, consolidate the docs, and produce a
> > > > shortlist
> > > > > of doc to fill in.
> > > > >
> > > > > However I did look at Gitbook (www.gitbook.com) and it looks quite
> > > > > interesting. How is the website/ documentation maintained at the
> > > moment?
> > > > > Would a tool like Gitbook enable better shared authoring or make
> > > content
> > > > > writing easier (eg rich text editor, not raw HTML)? These are
> > > interesting
> > > > > questions. It might also be possible to use gitbook to share
> writing,
> > > > then
> > > > > upload resulting HTML to an existing website repo if that's how
> > website
> > > > is
> > > > > maintained at the moment. See https://docs.duckduckhack.com/ for
> an
> > > > > example of Gitbook-produced docs.
> > > > >
> > > > >
> > > > we use a jbake site (
> > > > http://svn.apache.org/repos/asf/tomee/site/trunk/
> > > > generators/site-tomee-ng/src/main/jbake/
> > > > - development with tomee itself ;)) the we just sync with site
> content
> > > > http://svn.apache.org/repos/asf/tomee/site/trunk/content/ and push
> > > through
> > > > ASF mecanism ("CMS") which is basically a svn deployed on a click.
> Nice
> > > > thing of that tooling is the autostaging mode so you have a site
> > preview
> > > > before the prod one.
> > > >
> > > > So concretely we are in managed and public so already shareable. If
> > > github
> > > > is better we can sync with github like tomee itself, that's a detail.
> > And
> > > > we are adoc so github would just bring another structure but if you
> > check
> > > > we already have one. The search is interesting and I guess we'll need
> > to
> > > > add a kind of client search at build time or just use google.
> > > >
> > > >
> > > >
> > > >
> > > > > I would suggest that TomEE as a project is technically nice, but
> > > > > documentation may be holding it back. People on the mailing list
> are
> > > > great
> > > > > & very helpful and willing to answer questions, but I would believe
> > > that
> > > > > providing this material as findable written documentation on the
> > > current
> > > > > (new) website is important, as documentation is one of the #1
> things
> > > > people
> > > > > consider when considering a platform.
> > > > >
> > > > >
> > > > > Regards,
> > > > > Thomas
> > > > >
> > > > > -----Original Message-----
> > > > > From: Romain Manni-Bucau [mailto:rmannibucau@gmail.com]
> > > > > Sent: Friday, 10 March 2017 1:37 PM
> > > > > To: dev@tomee.apache.org
> > > > > Subject: Re: TomEE Documentation Suggestion
> > > > >
> > > > > Hi Ivan,
> > > > >
> > > > > we just revamped the website with a new structure, I know it is not
> > > > > perfect but a step to something better. Tooling is also way easier
> > now
> > > to
> > > > > get started with. So question is: what would bring gitbook which
> > would
> > > > make
> > > > > it better we don't have already? If github we can ask infra to
> proxy
> > > our
> > > > > site repo on ASF github org.
> > > > >
> > > > >
> > > > > Romain Manni-Bucau
> > > > > @rmannibucau <https://twitter.com/rmannibucau> | Blog <
> > > > > https://blog-rmannibucau.rhcloud.com> | Old Blog <
> > > > > http://rmannibucau.wordpress.com> | Github <https://github.com/
> > > > rmannibucau>
> > > > > | LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE
> > Factory
> > > <
> > > > > https://javaeefactory-rmannibucau.rhcloud.com>
> > > > >
> > > > > 2017-03-10 1:14 GMT+01:00 Ivan Junckes Filho <
> ivanjunckes@gmail.com
> > >:
> > > > >
> > > > > > Hello TomEE developers,
> > > > > >
> > > > > > Today TomEE documentation is spread across multiple places, some
> > are
> > > > > > not up to date anymore and some are just really hard to find on
> the
> > > > > > website. It is easier to find something on google than on
> > > > > http://tomee.apache.org.
> > > > > >
> > > > > > I would like to suggest that TomEE uses www.gitbook.com, and we
> > > > > > migrate there the relevant documentation. Updating a website with
> > doc
> > > > > > is ok, but I think it will make the job way easier and will open
> > the
> > > > > > gates for contributors.
> > > > >
> > > > > ____________________________________________________________
> > __________
> > > > > This email has been scanned by the Symantec Email Security.cloud
> > > service.
> > > > > For more information please visit http://www.symanteccloud.com
> > > > > ____________________________________________________________
> > __________
> > > > >
> > > >
> > >
> >
>
Re: TomEE Documentation Suggestion
Posted by Ivan Junckes Filho <iv...@gmail.com>.
As far as I understood JBake is a tool to generate websites (deal with
html, css etc.), what I am proposing is a tool to make the documentation
process friendly without caring with html, css, website structure etc.
We don't need to remove JBake from the website, but for documentation, we
can use a tool that is proven to work and make it simple.
I don't know where SEO has anything to do with this sorry, but the content
in gitbook is indexed on google if that it what you mean.
Well, just my suggestion, I was willing to help on that.
I would like to hear more thoughts from other developers if possible.
Thank you.
On Fri, Mar 10, 2017 at 8:10 AM, Romain Manni-Bucau <rm...@gmail.com>
wrote:
> 2017-03-10 12:02 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
>
> > Hi guys, thank you for the feedback.
> >
> > What would bring gitbook which would make it better we don't have
> already?
> > 1 - Documentation is a very tough thing to keep up to date, so we don't
> > want to make it hard for people to do it. What I see in gitbook is a very
> > straightforward way to update it and make it organized regardless of a
> > website.
> >
>
> Can you go one step further and say how compared to what we have it will
> help (it is the same kind of infra).
>
>
> > 2 - We'll have a tool that is specialized in this, websites need to be
> > redesigned over time and we don't want to be worrying about migrating all
> > the docs like we need to do now, from the old to the new.
> >
>
> JBake as well so once again not sure the gain
>
>
> > 3 - The tool is completely integrated with github, we'll have a project
> > inside the github with folders that we could even separate per language,
> > would be useful for example if someone with time could go there and
> create
> > a french folder and translate the docs.
> >
>
> Here again we can do it with jbake but have to admit I wonder if this
> someone exist after all the round trips and tries we got on the doc so I
> would prefer to take the opposite approad: if someone asks to translate the
> whole website we'll ensure it is setup than setting it up to nothing now.
>
>
> > 4 - We can easily have doc versioning, and make sure from now on when we
> > have a new feature we add it to the doc.
> >
>
> We can but decided to not do it cause majors arent really breaking.
>
>
> > 5 - Authoring is tracked by github itself and can be shared just like
> code
> >
>
> Same with svn today and once again no blocker to have a proxy on github.
>
>
> > 6 - Tool is based on .md (markdown) not html
> >
>
> adoc so better no? ;)
>
>
> > 7 - Maybe a straightforward way without learning curve can make people
> > start contributing?
> >
> >
> Learning curve for gitbook ~= jbake I think so not sure.
>
>
> > Imagine this scenario:
> > Let's say I am an application developer that uses TomEE and I learned
> > something about it that is not clear in the docs. I don't want to learn
> the
> > whole website thing (structure) etc, I just want to write it and send it
> in
> > an easy manner. This way seems pretty easy in my opinion.
> >
> > We need to make the environment welcoming if we want to improve this
> guys!
> >
> > These 2 JavaEE servers have some documentation and they don't keep on a
> > website, they use tools very similar to what I am proposing.
> >
> > Wildfly documentation
> > https://docs.jboss.org/author/display/WFLY10/Documentation
> >
> > Payara documentation
> > https://payara.gitbooks.io/payara-server/content/?
> > hsCtaTracking=8a4f0637-38ea-458c-a66c-6307d6f21923%
> > 7C26bb561b-3f60-4d3b-b64d-06398f00d8e2&__hstc=229474563.
> > 6de427338f64d2f474c236a686036ee9.1489142671622.
> > 1489142671622.1489142671622.1&__hssc=229474563.1.1489142671623&__hsfp=
> > 2299569188
> >
> > Even though I agree content is more important than tools, I think tools
> > help greatly if we choose the right ones, and they can avoid rework
> which I
> > am sure nobody wants to do if not necessary.
> >
> >
> So globally does your feedback means we need to proxy the website content
> on github and maybe enhance the SEO?
>
>
> >
> > On Fri, Mar 10, 2017 at 5:00 AM, Romain Manni-Bucau <
> rmannibucau@gmail.com
> > >
> > wrote:
> >
> > > 2017-03-10 3:16 GMT+01:00 Thomas Whitmore <twhitmore@bravurasolutions.
> > com
> > > >:
> > >
> > > > Hi Romain, Ivan,
> > > >
> > > > I agree with Romain and raised the suggestion of improving doc a
> month
> > or
> > > > two ago. At the time I offered a few hours to help -- am probably
> busy
> > > for
> > > > another month now but do see documentation as an important factor.
> > > >
> > > > My feeling would be that content is more important than tools -- I
> > would
> > > > see a librarian exercise to collect relevant docs and make them
> > > accessible
> > > > from the new site, as the most relevant. This I believe would give
> the
> > > most
> > > > easy and worthwhile improvement.
> > > >
> > > > My suggestion to move forward:
> > > > - collate docs from "old" openejb.apache.org site; get these
> reviewed
> > > > and edit to remove outdated material.
> > > > - reviewing/ marking of what's outdated & what can be
> corrected
> > > to
> > > > be delegated to appropriate people.
> > > > - make all docs accessible from Documentation areas on new
> > > > tomee.apache.org site;
> > > > - collect prioritized suggestions as to what documentation gaps
> remain.
> > > > - (probably also) for those who found the old site by accident, add
> > > links
> > > > from old site to new Documentation areas on tomee.apache.org site.
> > > >
> > > > This should make it possible to cheaply & easily gather all useful
> > > > material from existing docs, consolidate the docs, and produce a
> > > shortlist
> > > > of doc to fill in.
> > > >
> > > > However I did look at Gitbook (www.gitbook.com) and it looks quite
> > > > interesting. How is the website/ documentation maintained at the
> > moment?
> > > > Would a tool like Gitbook enable better shared authoring or make
> > content
> > > > writing easier (eg rich text editor, not raw HTML)? These are
> > interesting
> > > > questions. It might also be possible to use gitbook to share writing,
> > > then
> > > > upload resulting HTML to an existing website repo if that's how
> website
> > > is
> > > > maintained at the moment. See https://docs.duckduckhack.com/ for an
> > > > example of Gitbook-produced docs.
> > > >
> > > >
> > > we use a jbake site (
> > > http://svn.apache.org/repos/asf/tomee/site/trunk/
> > > generators/site-tomee-ng/src/main/jbake/
> > > - development with tomee itself ;)) the we just sync with site content
> > > http://svn.apache.org/repos/asf/tomee/site/trunk/content/ and push
> > through
> > > ASF mecanism ("CMS") which is basically a svn deployed on a click. Nice
> > > thing of that tooling is the autostaging mode so you have a site
> preview
> > > before the prod one.
> > >
> > > So concretely we are in managed and public so already shareable. If
> > github
> > > is better we can sync with github like tomee itself, that's a detail.
> And
> > > we are adoc so github would just bring another structure but if you
> check
> > > we already have one. The search is interesting and I guess we'll need
> to
> > > add a kind of client search at build time or just use google.
> > >
> > >
> > >
> > >
> > > > I would suggest that TomEE as a project is technically nice, but
> > > > documentation may be holding it back. People on the mailing list are
> > > great
> > > > & very helpful and willing to answer questions, but I would believe
> > that
> > > > providing this material as findable written documentation on the
> > current
> > > > (new) website is important, as documentation is one of the #1 things
> > > people
> > > > consider when considering a platform.
> > > >
> > > >
> > > > Regards,
> > > > Thomas
> > > >
> > > > -----Original Message-----
> > > > From: Romain Manni-Bucau [mailto:rmannibucau@gmail.com]
> > > > Sent: Friday, 10 March 2017 1:37 PM
> > > > To: dev@tomee.apache.org
> > > > Subject: Re: TomEE Documentation Suggestion
> > > >
> > > > Hi Ivan,
> > > >
> > > > we just revamped the website with a new structure, I know it is not
> > > > perfect but a step to something better. Tooling is also way easier
> now
> > to
> > > > get started with. So question is: what would bring gitbook which
> would
> > > make
> > > > it better we don't have already? If github we can ask infra to proxy
> > our
> > > > site repo on ASF github org.
> > > >
> > > >
> > > > Romain Manni-Bucau
> > > > @rmannibucau <https://twitter.com/rmannibucau> | Blog <
> > > > https://blog-rmannibucau.rhcloud.com> | Old Blog <
> > > > http://rmannibucau.wordpress.com> | Github <https://github.com/
> > > rmannibucau>
> > > > | LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE
> Factory
> > <
> > > > https://javaeefactory-rmannibucau.rhcloud.com>
> > > >
> > > > 2017-03-10 1:14 GMT+01:00 Ivan Junckes Filho <ivanjunckes@gmail.com
> >:
> > > >
> > > > > Hello TomEE developers,
> > > > >
> > > > > Today TomEE documentation is spread across multiple places, some
> are
> > > > > not up to date anymore and some are just really hard to find on the
> > > > > website. It is easier to find something on google than on
> > > > http://tomee.apache.org.
> > > > >
> > > > > I would like to suggest that TomEE uses www.gitbook.com, and we
> > > > > migrate there the relevant documentation. Updating a website with
> doc
> > > > > is ok, but I think it will make the job way easier and will open
> the
> > > > > gates for contributors.
> > > >
> > > > ____________________________________________________________
> __________
> > > > This email has been scanned by the Symantec Email Security.cloud
> > service.
> > > > For more information please visit http://www.symanteccloud.com
> > > > ____________________________________________________________
> __________
> > > >
> > >
> >
>
Re: TomEE Documentation Suggestion
Posted by Romain Manni-Bucau <rm...@gmail.com>.
2017-03-10 12:02 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
> Hi guys, thank you for the feedback.
>
> What would bring gitbook which would make it better we don't have already?
> 1 - Documentation is a very tough thing to keep up to date, so we don't
> want to make it hard for people to do it. What I see in gitbook is a very
> straightforward way to update it and make it organized regardless of a
> website.
>
Can you go one step further and say how compared to what we have it will
help (it is the same kind of infra).
> 2 - We'll have a tool that is specialized in this, websites need to be
> redesigned over time and we don't want to be worrying about migrating all
> the docs like we need to do now, from the old to the new.
>
JBake as well so once again not sure the gain
> 3 - The tool is completely integrated with github, we'll have a project
> inside the github with folders that we could even separate per language,
> would be useful for example if someone with time could go there and create
> a french folder and translate the docs.
>
Here again we can do it with jbake but have to admit I wonder if this
someone exist after all the round trips and tries we got on the doc so I
would prefer to take the opposite approad: if someone asks to translate the
whole website we'll ensure it is setup than setting it up to nothing now.
> 4 - We can easily have doc versioning, and make sure from now on when we
> have a new feature we add it to the doc.
>
We can but decided to not do it cause majors arent really breaking.
> 5 - Authoring is tracked by github itself and can be shared just like code
>
Same with svn today and once again no blocker to have a proxy on github.
> 6 - Tool is based on .md (markdown) not html
>
adoc so better no? ;)
> 7 - Maybe a straightforward way without learning curve can make people
> start contributing?
>
>
Learning curve for gitbook ~= jbake I think so not sure.
> Imagine this scenario:
> Let's say I am an application developer that uses TomEE and I learned
> something about it that is not clear in the docs. I don't want to learn the
> whole website thing (structure) etc, I just want to write it and send it in
> an easy manner. This way seems pretty easy in my opinion.
>
> We need to make the environment welcoming if we want to improve this guys!
>
> These 2 JavaEE servers have some documentation and they don't keep on a
> website, they use tools very similar to what I am proposing.
>
> Wildfly documentation
> https://docs.jboss.org/author/display/WFLY10/Documentation
>
> Payara documentation
> https://payara.gitbooks.io/payara-server/content/?
> hsCtaTracking=8a4f0637-38ea-458c-a66c-6307d6f21923%
> 7C26bb561b-3f60-4d3b-b64d-06398f00d8e2&__hstc=229474563.
> 6de427338f64d2f474c236a686036ee9.1489142671622.
> 1489142671622.1489142671622.1&__hssc=229474563.1.1489142671623&__hsfp=
> 2299569188
>
> Even though I agree content is more important than tools, I think tools
> help greatly if we choose the right ones, and they can avoid rework which I
> am sure nobody wants to do if not necessary.
>
>
So globally does your feedback means we need to proxy the website content
on github and maybe enhance the SEO?
>
> On Fri, Mar 10, 2017 at 5:00 AM, Romain Manni-Bucau <rmannibucau@gmail.com
> >
> wrote:
>
> > 2017-03-10 3:16 GMT+01:00 Thomas Whitmore <twhitmore@bravurasolutions.
> com
> > >:
> >
> > > Hi Romain, Ivan,
> > >
> > > I agree with Romain and raised the suggestion of improving doc a month
> or
> > > two ago. At the time I offered a few hours to help -- am probably busy
> > for
> > > another month now but do see documentation as an important factor.
> > >
> > > My feeling would be that content is more important than tools -- I
> would
> > > see a librarian exercise to collect relevant docs and make them
> > accessible
> > > from the new site, as the most relevant. This I believe would give the
> > most
> > > easy and worthwhile improvement.
> > >
> > > My suggestion to move forward:
> > > - collate docs from "old" openejb.apache.org site; get these reviewed
> > > and edit to remove outdated material.
> > > - reviewing/ marking of what's outdated & what can be corrected
> > to
> > > be delegated to appropriate people.
> > > - make all docs accessible from Documentation areas on new
> > > tomee.apache.org site;
> > > - collect prioritized suggestions as to what documentation gaps remain.
> > > - (probably also) for those who found the old site by accident, add
> > links
> > > from old site to new Documentation areas on tomee.apache.org site.
> > >
> > > This should make it possible to cheaply & easily gather all useful
> > > material from existing docs, consolidate the docs, and produce a
> > shortlist
> > > of doc to fill in.
> > >
> > > However I did look at Gitbook (www.gitbook.com) and it looks quite
> > > interesting. How is the website/ documentation maintained at the
> moment?
> > > Would a tool like Gitbook enable better shared authoring or make
> content
> > > writing easier (eg rich text editor, not raw HTML)? These are
> interesting
> > > questions. It might also be possible to use gitbook to share writing,
> > then
> > > upload resulting HTML to an existing website repo if that's how website
> > is
> > > maintained at the moment. See https://docs.duckduckhack.com/ for an
> > > example of Gitbook-produced docs.
> > >
> > >
> > we use a jbake site (
> > http://svn.apache.org/repos/asf/tomee/site/trunk/
> > generators/site-tomee-ng/src/main/jbake/
> > - development with tomee itself ;)) the we just sync with site content
> > http://svn.apache.org/repos/asf/tomee/site/trunk/content/ and push
> through
> > ASF mecanism ("CMS") which is basically a svn deployed on a click. Nice
> > thing of that tooling is the autostaging mode so you have a site preview
> > before the prod one.
> >
> > So concretely we are in managed and public so already shareable. If
> github
> > is better we can sync with github like tomee itself, that's a detail. And
> > we are adoc so github would just bring another structure but if you check
> > we already have one. The search is interesting and I guess we'll need to
> > add a kind of client search at build time or just use google.
> >
> >
> >
> >
> > > I would suggest that TomEE as a project is technically nice, but
> > > documentation may be holding it back. People on the mailing list are
> > great
> > > & very helpful and willing to answer questions, but I would believe
> that
> > > providing this material as findable written documentation on the
> current
> > > (new) website is important, as documentation is one of the #1 things
> > people
> > > consider when considering a platform.
> > >
> > >
> > > Regards,
> > > Thomas
> > >
> > > -----Original Message-----
> > > From: Romain Manni-Bucau [mailto:rmannibucau@gmail.com]
> > > Sent: Friday, 10 March 2017 1:37 PM
> > > To: dev@tomee.apache.org
> > > Subject: Re: TomEE Documentation Suggestion
> > >
> > > Hi Ivan,
> > >
> > > we just revamped the website with a new structure, I know it is not
> > > perfect but a step to something better. Tooling is also way easier now
> to
> > > get started with. So question is: what would bring gitbook which would
> > make
> > > it better we don't have already? If github we can ask infra to proxy
> our
> > > site repo on ASF github org.
> > >
> > >
> > > Romain Manni-Bucau
> > > @rmannibucau <https://twitter.com/rmannibucau> | Blog <
> > > https://blog-rmannibucau.rhcloud.com> | Old Blog <
> > > http://rmannibucau.wordpress.com> | Github <https://github.com/
> > rmannibucau>
> > > | LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
> <
> > > https://javaeefactory-rmannibucau.rhcloud.com>
> > >
> > > 2017-03-10 1:14 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
> > >
> > > > Hello TomEE developers,
> > > >
> > > > Today TomEE documentation is spread across multiple places, some are
> > > > not up to date anymore and some are just really hard to find on the
> > > > website. It is easier to find something on google than on
> > > http://tomee.apache.org.
> > > >
> > > > I would like to suggest that TomEE uses www.gitbook.com, and we
> > > > migrate there the relevant documentation. Updating a website with doc
> > > > is ok, but I think it will make the job way easier and will open the
> > > > gates for contributors.
> > >
> > > ______________________________________________________________________
> > > This email has been scanned by the Symantec Email Security.cloud
> service.
> > > For more information please visit http://www.symanteccloud.com
> > > ______________________________________________________________________
> > >
> >
>
Re: TomEE Documentation Suggestion
Posted by Ivan Junckes Filho <iv...@gmail.com>.
Hi guys, thank you for the feedback.
What would bring gitbook which would make it better we don't have already?
1 - Documentation is a very tough thing to keep up to date, so we don't
want to make it hard for people to do it. What I see in gitbook is a very
straightforward way to update it and make it organized regardless of a
website.
2 - We'll have a tool that is specialized in this, websites need to be
redesigned over time and we don't want to be worrying about migrating all
the docs like we need to do now, from the old to the new.
3 - The tool is completely integrated with github, we'll have a project
inside the github with folders that we could even separate per language,
would be useful for example if someone with time could go there and create
a french folder and translate the docs.
4 - We can easily have doc versioning, and make sure from now on when we
have a new feature we add it to the doc.
5 - Authoring is tracked by github itself and can be shared just like code
6 - Tool is based on .md (markdown) not html
7 - Maybe a straightforward way without learning curve can make people
start contributing?
Imagine this scenario:
Let's say I am an application developer that uses TomEE and I learned
something about it that is not clear in the docs. I don't want to learn the
whole website thing (structure) etc, I just want to write it and send it in
an easy manner. This way seems pretty easy in my opinion.
We need to make the environment welcoming if we want to improve this guys!
These 2 JavaEE servers have some documentation and they don't keep on a
website, they use tools very similar to what I am proposing.
Wildfly documentation
https://docs.jboss.org/author/display/WFLY10/Documentation
Payara documentation
https://payara.gitbooks.io/payara-server/content/?hsCtaTracking=8a4f0637-38ea-458c-a66c-6307d6f21923%7C26bb561b-3f60-4d3b-b64d-06398f00d8e2&__hstc=229474563.6de427338f64d2f474c236a686036ee9.1489142671622.1489142671622.1489142671622.1&__hssc=229474563.1.1489142671623&__hsfp=2299569188
Even though I agree content is more important than tools, I think tools
help greatly if we choose the right ones, and they can avoid rework which I
am sure nobody wants to do if not necessary.
On Fri, Mar 10, 2017 at 5:00 AM, Romain Manni-Bucau <rm...@gmail.com>
wrote:
> 2017-03-10 3:16 GMT+01:00 Thomas Whitmore <twhitmore@bravurasolutions.com
> >:
>
> > Hi Romain, Ivan,
> >
> > I agree with Romain and raised the suggestion of improving doc a month or
> > two ago. At the time I offered a few hours to help -- am probably busy
> for
> > another month now but do see documentation as an important factor.
> >
> > My feeling would be that content is more important than tools -- I would
> > see a librarian exercise to collect relevant docs and make them
> accessible
> > from the new site, as the most relevant. This I believe would give the
> most
> > easy and worthwhile improvement.
> >
> > My suggestion to move forward:
> > - collate docs from "old" openejb.apache.org site; get these reviewed
> > and edit to remove outdated material.
> > - reviewing/ marking of what's outdated & what can be corrected
> to
> > be delegated to appropriate people.
> > - make all docs accessible from Documentation areas on new
> > tomee.apache.org site;
> > - collect prioritized suggestions as to what documentation gaps remain.
> > - (probably also) for those who found the old site by accident, add
> links
> > from old site to new Documentation areas on tomee.apache.org site.
> >
> > This should make it possible to cheaply & easily gather all useful
> > material from existing docs, consolidate the docs, and produce a
> shortlist
> > of doc to fill in.
> >
> > However I did look at Gitbook (www.gitbook.com) and it looks quite
> > interesting. How is the website/ documentation maintained at the moment?
> > Would a tool like Gitbook enable better shared authoring or make content
> > writing easier (eg rich text editor, not raw HTML)? These are interesting
> > questions. It might also be possible to use gitbook to share writing,
> then
> > upload resulting HTML to an existing website repo if that's how website
> is
> > maintained at the moment. See https://docs.duckduckhack.com/ for an
> > example of Gitbook-produced docs.
> >
> >
> we use a jbake site (
> http://svn.apache.org/repos/asf/tomee/site/trunk/
> generators/site-tomee-ng/src/main/jbake/
> - development with tomee itself ;)) the we just sync with site content
> http://svn.apache.org/repos/asf/tomee/site/trunk/content/ and push through
> ASF mecanism ("CMS") which is basically a svn deployed on a click. Nice
> thing of that tooling is the autostaging mode so you have a site preview
> before the prod one.
>
> So concretely we are in managed and public so already shareable. If github
> is better we can sync with github like tomee itself, that's a detail. And
> we are adoc so github would just bring another structure but if you check
> we already have one. The search is interesting and I guess we'll need to
> add a kind of client search at build time or just use google.
>
>
>
>
> > I would suggest that TomEE as a project is technically nice, but
> > documentation may be holding it back. People on the mailing list are
> great
> > & very helpful and willing to answer questions, but I would believe that
> > providing this material as findable written documentation on the current
> > (new) website is important, as documentation is one of the #1 things
> people
> > consider when considering a platform.
> >
> >
> > Regards,
> > Thomas
> >
> > -----Original Message-----
> > From: Romain Manni-Bucau [mailto:rmannibucau@gmail.com]
> > Sent: Friday, 10 March 2017 1:37 PM
> > To: dev@tomee.apache.org
> > Subject: Re: TomEE Documentation Suggestion
> >
> > Hi Ivan,
> >
> > we just revamped the website with a new structure, I know it is not
> > perfect but a step to something better. Tooling is also way easier now to
> > get started with. So question is: what would bring gitbook which would
> make
> > it better we don't have already? If github we can ask infra to proxy our
> > site repo on ASF github org.
> >
> >
> > Romain Manni-Bucau
> > @rmannibucau <https://twitter.com/rmannibucau> | Blog <
> > https://blog-rmannibucau.rhcloud.com> | Old Blog <
> > http://rmannibucau.wordpress.com> | Github <https://github.com/
> rmannibucau>
> > | LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory <
> > https://javaeefactory-rmannibucau.rhcloud.com>
> >
> > 2017-03-10 1:14 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
> >
> > > Hello TomEE developers,
> > >
> > > Today TomEE documentation is spread across multiple places, some are
> > > not up to date anymore and some are just really hard to find on the
> > > website. It is easier to find something on google than on
> > http://tomee.apache.org.
> > >
> > > I would like to suggest that TomEE uses www.gitbook.com, and we
> > > migrate there the relevant documentation. Updating a website with doc
> > > is ok, but I think it will make the job way easier and will open the
> > > gates for contributors.
> >
> > ______________________________________________________________________
> > This email has been scanned by the Symantec Email Security.cloud service.
> > For more information please visit http://www.symanteccloud.com
> > ______________________________________________________________________
> >
>
Re: TomEE Documentation Suggestion
Posted by Romain Manni-Bucau <rm...@gmail.com>.
2017-03-10 3:16 GMT+01:00 Thomas Whitmore <tw...@bravurasolutions.com>:
> Hi Romain, Ivan,
>
> I agree with Romain and raised the suggestion of improving doc a month or
> two ago. At the time I offered a few hours to help -- am probably busy for
> another month now but do see documentation as an important factor.
>
> My feeling would be that content is more important than tools -- I would
> see a librarian exercise to collect relevant docs and make them accessible
> from the new site, as the most relevant. This I believe would give the most
> easy and worthwhile improvement.
>
> My suggestion to move forward:
> - collate docs from "old" openejb.apache.org site; get these reviewed
> and edit to remove outdated material.
> - reviewing/ marking of what's outdated & what can be corrected to
> be delegated to appropriate people.
> - make all docs accessible from Documentation areas on new
> tomee.apache.org site;
> - collect prioritized suggestions as to what documentation gaps remain.
> - (probably also) for those who found the old site by accident, add links
> from old site to new Documentation areas on tomee.apache.org site.
>
> This should make it possible to cheaply & easily gather all useful
> material from existing docs, consolidate the docs, and produce a shortlist
> of doc to fill in.
>
> However I did look at Gitbook (www.gitbook.com) and it looks quite
> interesting. How is the website/ documentation maintained at the moment?
> Would a tool like Gitbook enable better shared authoring or make content
> writing easier (eg rich text editor, not raw HTML)? These are interesting
> questions. It might also be possible to use gitbook to share writing, then
> upload resulting HTML to an existing website repo if that's how website is
> maintained at the moment. See https://docs.duckduckhack.com/ for an
> example of Gitbook-produced docs.
>
>
we use a jbake site (
http://svn.apache.org/repos/asf/tomee/site/trunk/generators/site-tomee-ng/src/main/jbake/
- development with tomee itself ;)) the we just sync with site content
http://svn.apache.org/repos/asf/tomee/site/trunk/content/ and push through
ASF mecanism ("CMS") which is basically a svn deployed on a click. Nice
thing of that tooling is the autostaging mode so you have a site preview
before the prod one.
So concretely we are in managed and public so already shareable. If github
is better we can sync with github like tomee itself, that's a detail. And
we are adoc so github would just bring another structure but if you check
we already have one. The search is interesting and I guess we'll need to
add a kind of client search at build time or just use google.
> I would suggest that TomEE as a project is technically nice, but
> documentation may be holding it back. People on the mailing list are great
> & very helpful and willing to answer questions, but I would believe that
> providing this material as findable written documentation on the current
> (new) website is important, as documentation is one of the #1 things people
> consider when considering a platform.
>
>
> Regards,
> Thomas
>
> -----Original Message-----
> From: Romain Manni-Bucau [mailto:rmannibucau@gmail.com]
> Sent: Friday, 10 March 2017 1:37 PM
> To: dev@tomee.apache.org
> Subject: Re: TomEE Documentation Suggestion
>
> Hi Ivan,
>
> we just revamped the website with a new structure, I know it is not
> perfect but a step to something better. Tooling is also way easier now to
> get started with. So question is: what would bring gitbook which would make
> it better we don't have already? If github we can ask infra to proxy our
> site repo on ASF github org.
>
>
> Romain Manni-Bucau
> @rmannibucau <https://twitter.com/rmannibucau> | Blog <
> https://blog-rmannibucau.rhcloud.com> | Old Blog <
> http://rmannibucau.wordpress.com> | Github <https://github.com/rmannibucau>
> | LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory <
> https://javaeefactory-rmannibucau.rhcloud.com>
>
> 2017-03-10 1:14 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
>
> > Hello TomEE developers,
> >
> > Today TomEE documentation is spread across multiple places, some are
> > not up to date anymore and some are just really hard to find on the
> > website. It is easier to find something on google than on
> http://tomee.apache.org.
> >
> > I would like to suggest that TomEE uses www.gitbook.com, and we
> > migrate there the relevant documentation. Updating a website with doc
> > is ok, but I think it will make the job way easier and will open the
> > gates for contributors.
>
> ______________________________________________________________________
> This email has been scanned by the Symantec Email Security.cloud service.
> For more information please visit http://www.symanteccloud.com
> ______________________________________________________________________
>
RE: TomEE Documentation Suggestion
Posted by Thomas Whitmore <tw...@bravurasolutions.com>.
Hi Romain, Ivan,
I agree with Romain and raised the suggestion of improving doc a month or two ago. At the time I offered a few hours to help -- am probably busy for another month now but do see documentation as an important factor.
My feeling would be that content is more important than tools -- I would see a librarian exercise to collect relevant docs and make them accessible from the new site, as the most relevant. This I believe would give the most easy and worthwhile improvement.
My suggestion to move forward:
- collate docs from "old" openejb.apache.org site; get these reviewed and edit to remove outdated material.
- reviewing/ marking of what's outdated & what can be corrected to be delegated to appropriate people.
- make all docs accessible from Documentation areas on new tomee.apache.org site;
- collect prioritized suggestions as to what documentation gaps remain.
- (probably also) for those who found the old site by accident, add links from old site to new Documentation areas on tomee.apache.org site.
This should make it possible to cheaply & easily gather all useful material from existing docs, consolidate the docs, and produce a shortlist of doc to fill in.
However I did look at Gitbook (www.gitbook.com) and it looks quite interesting. How is the website/ documentation maintained at the moment? Would a tool like Gitbook enable better shared authoring or make content writing easier (eg rich text editor, not raw HTML)? These are interesting questions. It might also be possible to use gitbook to share writing, then upload resulting HTML to an existing website repo if that's how website is maintained at the moment. See https://docs.duckduckhack.com/ for an example of Gitbook-produced docs.
I would suggest that TomEE as a project is technically nice, but documentation may be holding it back. People on the mailing list are great & very helpful and willing to answer questions, but I would believe that providing this material as findable written documentation on the current (new) website is important, as documentation is one of the #1 things people consider when considering a platform.
Regards,
Thomas
-----Original Message-----
From: Romain Manni-Bucau [mailto:rmannibucau@gmail.com]
Sent: Friday, 10 March 2017 1:37 PM
To: dev@tomee.apache.org
Subject: Re: TomEE Documentation Suggestion
Hi Ivan,
we just revamped the website with a new structure, I know it is not perfect but a step to something better. Tooling is also way easier now to get started with. So question is: what would bring gitbook which would make it better we don't have already? If github we can ask infra to proxy our site repo on ASF github org.
Romain Manni-Bucau
@rmannibucau <https://twitter.com/rmannibucau> | Blog <https://blog-rmannibucau.rhcloud.com> | Old Blog <http://rmannibucau.wordpress.com> | Github <https://github.com/rmannibucau> | LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory <https://javaeefactory-rmannibucau.rhcloud.com>
2017-03-10 1:14 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
> Hello TomEE developers,
>
> Today TomEE documentation is spread across multiple places, some are
> not up to date anymore and some are just really hard to find on the
> website. It is easier to find something on google than on http://tomee.apache.org.
>
> I would like to suggest that TomEE uses www.gitbook.com, and we
> migrate there the relevant documentation. Updating a website with doc
> is ok, but I think it will make the job way easier and will open the
> gates for contributors.
______________________________________________________________________
This email has been scanned by the Symantec Email Security.cloud service.
For more information please visit http://www.symanteccloud.com
______________________________________________________________________
Re: TomEE Documentation Suggestion
Posted by Romain Manni-Bucau <rm...@gmail.com>.
Hi Ivan,
we just revamped the website with a new structure, I know it is not perfect
but a step to something better. Tooling is also way easier now to get
started with. So question is: what would bring gitbook which would make it
better we don't have already? If github we can ask infra to proxy our site
repo on ASF github org.
Romain Manni-Bucau
@rmannibucau <https://twitter.com/rmannibucau> | Blog
<https://blog-rmannibucau.rhcloud.com> | Old Blog
<http://rmannibucau.wordpress.com> | Github <https://github.com/rmannibucau> |
LinkedIn <https://www.linkedin.com/in/rmannibucau> | JavaEE Factory
<https://javaeefactory-rmannibucau.rhcloud.com>
2017-03-10 1:14 GMT+01:00 Ivan Junckes Filho <iv...@gmail.com>:
> Hello TomEE developers,
>
> Today TomEE documentation is spread across multiple places, some are not up
> to date anymore and some are just really hard to find on the website. It is
> easier to find something on google than on http://tomee.apache.org.
>
> I would like to suggest that TomEE uses www.gitbook.com, and we migrate
> there the relevant documentation. Updating a website with doc is ok, but I
> think it will make the job way easier and will open the gates for
> contributors.
>
> All of us here are interested in TomEE documentation to get better and I
> think that is a good start, we will not need to keep updating the website,
> maintain pages etc we'll just need to use centralized tool.
>
> Please let me know your thoughts.
>
> Please see JNoSQL documentation as a reference:
> https://www.gitbook.com/book/jnosql/jnosql-book/details
> https://github.com/jnoSQL/jnosql-book
>
> Thank you.
>
> +1? -1?
>