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
