activemq-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "John D. Ament" <john.d.am...@gmail.com>
Subject Re: How to rebuild the docs for Artemis?
Date Mon, 14 Nov 2016 19:33:11 GMT
On Mon, Nov 14, 2016 at 11:11 AM Martyn Taylor <mtaylor@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 <johndament@apache.org>
> wrote:
>
> > On Mon, Nov 14, 2016 at 10:29 AM Clebert Suconic <
> > clebert.suconic@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.
> > >
> >
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message