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 <[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 > > > > ____________________________________________________________ > __________ > > > > > > > > > >
