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 <[email protected]>: > > > Le 10 mars 2017 13:04, "Ivan Junckes Filho" <[email protected]> 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 <[email protected] > > > wrote: > > > 2017-03-10 12:38 GMT+01:00 Ivan Junckes Filho <[email protected]>: > > > > > 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 < > > [email protected] > > > > > > > wrote: > > > > > > > 2017-03-10 12:02 GMT+01:00 Ivan Junckes Filho <[email protected] > >: > > > > > > > > > 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 < > > > > [email protected] > > > > > > > > > > > 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:[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 > > > > > > > ____________________________________________________________ > > > > __________ > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
