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 <[email protected]> wrote: > 2017-03-10 3:16 GMT+01:00 Thomas Whitmore <[email protected] > >: > > > 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:[email protected]] > > Sent: Friday, 10 March 2017 1:37 PM > > To: [email protected] > > 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 <[email protected]>: > > > > > 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 > > ______________________________________________________________________ > > >
