On Mon, Nov 14, 2016 at 11:11 AM Martyn Taylor <mtay...@redhat.com> wrote:
> I'm not 100% I am following properly here, but a couple of points: > > The documentation API/user manual is currently shipped with the release. > So there's no way to update this after the release is out. We do host > copies of the documentation (and some additional formats) here: > > https://activemq.apache.org/artemis/docs.html > > These could be updated after a release. But would mean there's a > differences between what we ship and what we host online. If we want to > separate the documentation and the release, then perhaps we remove the docs > from the release altogether, and point users our docs page, which we can > update periodically? > > John, regarding your comments about pushing to docs periodically, could you > please explain how this works? could you point to me to a project that does > this so I can take a look? > Basically, 95% of apache ships user docs for current release on their website, even as a part of development cycles. If I look at projects like Tomcat, they're keeping the latest old version online, so 8.0.x is grouped, 8.5.x, 7.0.x etc. TomEE on the flipside has a good approach - http://tomee.apache.org/documentation.html Basically, where there's something not compatible, its a different page (look at the spring section) And just because its highly relevant to us - this is how Kafka is structured: https://github.com/apache/kafka-site User docs fully decoupled from source. > > Thanks > Martyn > > > > > > On Mon, Nov 14, 2016 at 3:46 PM, John D. Ament <johndam...@apache.org> > wrote: > > > On Mon, Nov 14, 2016 at 10:29 AM Clebert Suconic < > > clebert.suco...@gmail.com> > > wrote: > > > > > > 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. > > > > > > > > > > That would encourage snapshot usage IMO. > > > > > > > I don't understand this point. The ASF acknowledges snapshots. There's > > nothing wrong with snapshots, as long as its clear that: > > > > - Its not an official release > > - Taking the "official release" isn't a process involving cloning the > > current master/head of the repo. > > > > Do you have concerns with using snapshots? I think its actually a good > > practice, to make sure there's no compatibility issues for users or > > ourselves. > > > > > > > As of now I will just update 1.5.0 HTML with the change you made. > > > > > >
