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