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