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