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 > ______________________________________________________________________ >
