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