+1 for asciidoc
Andy Gumbrecht.
On 19/09/17 10:15, Jean-Louis Monteiro wrote:
I totally agree that our documentation is a pain and does not help us first
to right it and contributors to help.
Each time I have to do a fix or add something it's a pain.
So +1 to simplify it.
JBake, plain asciidoc, whatever. Just something simple.
--
Jean-Louis Monteiro
http://twitter.com/jlouismonteiro
http://www.tomitribe.com
On Sun, Sep 17, 2017 at 8:09 AM, Romain Manni-Bucau <[email protected]>
wrote:
+0 to have it all and sync somehow in the site build process - i like
having it with the code since it enables some more stuff to happen but it
increases contribution cost
-0 to have it partially to ensure we dont loose contributors
Side note: if you import it, ensure to update all the contributor docs and
github proxies please
Side note 2: we can still generate doc in another project depending on main
artifacts ;)
Le 17 sept. 2017 05:26, "David Blevins" <[email protected]> a écrit
:
Just wrote a long description on the definition of InvocationTime and
MonitoredMethods in the JMX `@Monitor` functionality and I'm reminded on
how much of a pain it is to contribute to the documentation. It would be
so much easier if some part of it was in the build.
I'm wondering if we want some sort of docs/ directory in our main repo.
Not thinking we add jbake to the main build, just the asciidoc. The
fancy
processing can still happen elsewhere.
Docs like "how to contribute to the website" would stay where they are,
but things like "configuring datasources" would definitely come in. We'd
then follow the Tomcat approach of:
- https://tomcat.apache.org/tomcat-8.5-doc/index.html <
https://tomcat.apache.org/tomcat-8.5-doc/index.html>
- https://tomcat.apache.org/tomcat-8.0-doc/index.html <
https://tomcat.apache.org/tomcat-8.0-doc/index.html>
etc.
I don't think we'd need to get too fancy and do one doc base per Web
Profile, Plume, etc. just this would be enough:
- https://tomee.apache.org/tomee-8.0-doc/index.html <
https://tomee.apache.org/tomee-8.0-doc/index.html>
- https://tomee.apache.org/tomee-7.0-doc/index.html <
https://tomee.apache.org/tomee-7.0-doc/index.html>
- https://tomee.apache.org/tomee-1.7-doc/index.html <
https://tomee.apache.org/tomee-1.7-doc/index.html>
When sheldon/chatterbox come in, they'd go:
- https://tomee.apache.org/sheldon-3.0-doc/index.html <
https://tomee.apache.org/sheldon-3.0-doc/index.html>
- https://tomee.apache.org/chatterbox-2.1-doc/index.html <
https://tomee.apache.org/chatterbox-2.1-doc/index.html>
I totally made up those version numbers for illustrative purposes. You
get the idea.
Related note, we actually have some documentation generated from the
build
and not regenerated. This page for example was entirely generated from
the
default service-jar.xml:
- http://tomee.apache.org/containers-and-resources.html <
http://tomee.apache.org/containers-and-resources.html>
I remember doing that ages ago, like 2008-2011 range. Aside from being
likely out of date, it definitely highlights the awkward relationship
between the docs and the source we currently have.
--
David Blevins
http://twitter.com/dblevins
http://www.tomitribe.com
