On Fri, Nov 11, 2016 at 2:57 PM Justin Bertram <jbert...@apache.com> wrote:
> > Most projects treat their documentation as continuous. Committers can > push in changes whenever relevant. > > Certainly a case can be made for wiki-style documentation that is outside > the code-base and can be visibly updated at any point. I've worked with > documentation like that, and while it was convenient for some things it > usually became cumbersome as the software matured and features were added, > deprecated, etc. Extra bits of documentation needed to be added to > articles indicating which versions supported what functionality, etc. > > I much prefer keeping the documentation as part of the code-base so it is > versioned and tracked appropriately along with the software. Each release > has its own version of the documentation so it is clear what version it > applies to. JIRAs can be opened for documentation fixes, etc. Aside from > ad hoc updates to fix small errors I'm not currently aware of any use-cases > where the wiki-style approach is superior. > I'm against the idea of storing the docs outside the source repository. It just makes sense for them to live together. When you're looking at a release bundle, the docs within it should match the release you pulled down. I don't have an issue with us hosting multiple releases worth of docs, even though at apache we only ever consider the latest release as valid. I think it would be beneficial for us to have docs setup for the current snapshot as well. This way we can see if users have feedback on the current goings on. That's where I'm talking about the continuous aspect of this. They could even go into a SNAPSHOT folder. BTW, neither of these emails tell me how to build the docs ;-) Any hints? > > > Justin > > ----- Original Message ----- > From: "John D. Ament" <johndam...@apache.org> > To: dev@activemq.apache.org > Sent: Friday, November 11, 2016 10:44:12 AM > Subject: How to rebuild the docs for Artemis? > > All, > > I just filed https://issues.apache.org/jira/browse/ARTEMIS-849 as I saw > the > CDI integration docs were missing (was discussing with someone who was > interested, and the link didn't work for me). I suspect that the reason > they're not working is because its not on the SUMMARY file. > > What I don't see is how to actually rebuild the docs locally. There's no > pom file in docs. Is there something else that generate the documentation > folder? In fact the hacking guide indicates its via maven - > > https://github.com/apache/activemq-artemis/blob/master/docs/hacking-guide/en/building.md > . > > The other thing that I'm not sure about is if the docs can only be updated > within the release, or if we can patch them after the release has gone > out? I don't think this warrants a 1.5.1, but at the same time would like > to see it fixed before another release goes out. > > Most projects treat their documentation as continuous. Committers can push > in changes whenever relevant. > > John >
