[DISCUSS] Single version docs on Artemis

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
14 messages Options
Reply | Threaded
Open this post in threaded view
|

[DISCUSS] Single version docs on Artemis

clebertsuconic
this made sense at first (at least I think it did), but now that We
will have 10 versions (and counting) of Artemis... this seems a bit
too much...

http://activemq.apache.org/artemis/docs.html


I was wondering if we could / should update the docs page to only
include the latest version (that is 2.0.0)... The docs are still
maintained at the git, so you can always refer to the doc of the
version you're using when you download.. or you can use links from
github.


That would also make it easier for web robots (google, etc)  to index it.



Thoughts?



--
Clebert Suconic
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

Jiri Danek
On Mon, Mar 13, 2017 at 6:27 PM, Clebert Suconic <[hidden email]>
wrote:

> I was wondering if we could / should update the docs page to only
> include the latest version (that is 2.0.0)... The docs are still
> maintained at the git, so you can always refer to the doc of the
> version you're using when you download.. or you can use links from
> github.
>

It seems strange to maintain the 1.x release stream and not have
documentation for it on the site. There should be at least the latest 1,x
and the latest 2.0 version.

The projects whose documentation I often browse online all have previous
doc versions on the site, be it https://www.postgresql.org/docs/, Python or
readthedocs.io hosted sites like http://docs.pachyderm.io/en/stable/ (see
the version picker at the bottom left).

readthedocs.io sites also have a noticebar that alerts users that they are
browsing documentation for older release; I once raised this as feature
request https://issues.apache.org/jira/browse/ARTEMIS-615


> That would also make it easier for web robots (google, etc)  to index it.
>
<link href="http://www.example.com/canonical-version-of-page/"
rel="canonical" />

in the HTML head section should take care of that. This is what
readthedocs.io does.
--
Jiří Daněk
Messaging QA
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

nigro_franz
+1
Just reducing all the 1.x.y docs to the latest 1.x + the latest 2.0 would be great and will help the users leaving only common uses choices simpler.
And as Clebert pointed, it will help web robots too...
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

tabish121@gmail.com
In reply to this post by clebertsuconic
On 03/13/2017 01:27 PM, Clebert Suconic wrote:

> this made sense at first (at least I think it did), but now that We
> will have 10 versions (and counting) of Artemis... this seems a bit
> too much...
>
> http://activemq.apache.org/artemis/docs.html
>
>
> I was wondering if we could / should update the docs page to only
> include the latest version (that is 2.0.0)... The docs are still
> maintained at the git, so you can always refer to the doc of the
> version you're using when you download.. or you can use links from
> github.
>
>
> That would also make it easier for web robots (google, etc)  to index it.
>
>
>
> Thoughts?
>
>
>
While we've been a bit fuzzy in the past about what versions (how far
back) we go on supported releases it seems reasonable to me to keep docs
for the current (latest version) release and docs for one release
iteration back.  So soon'ish I'd expect that I'd find docs for 2.0.0 and
1.5.4.  I don't think you need to keep them all on the site but I'd at
least expect to see the one's for the current supported release
streams.  You could keep a few older one's if you wanted to be kind but
don't necessarily need to keep them all.  If you had supported and links
or instruction on how to get them for past releases that'd be a nice
compromise.


--
Tim Bish
twitter: @tabish121
blog: http://timbish.blogspot.com/

Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

clebertsuconic
In reply to this post by Jiri Danek
Sure.   Latest 1.x and latest 2.x.



Just that it seems too much now.




On Mon, Mar 13, 2017 at 1:42 PM Jiri Danek <[hidden email]> wrote:

> On Mon, Mar 13, 2017 at 6:27 PM, Clebert Suconic <
> [hidden email]>
> wrote:
>
> > I was wondering if we could / should update the docs page to only
> > include the latest version (that is 2.0.0)... The docs are still
> > maintained at the git, so you can always refer to the doc of the
> > version you're using when you download.. or you can use links from
> > github.
> >
>
> It seems strange to maintain the 1.x release stream and not have
> documentation for it on the site. There should be at least the latest 1,x
> and the latest 2.0 version.
>
> The projects whose documentation I often browse online all have previous
> doc versions on the site, be it https://www.postgresql.org/docs/, Python
> or
> readthedocs.io hosted sites like http://docs.pachyderm.io/en/stable/ (see
> the version picker at the bottom left).
>
> readthedocs.io sites also have a noticebar that alerts users that they are
> browsing documentation for older release; I once raised this as feature
> request https://issues.apache.org/jira/browse/ARTEMIS-615
>
>
> > That would also make it easier for web robots (google, etc)  to index it.
> >
> <link href="http://www.example.com/canonical-version-of-page/"
> rel="canonical" />
>
> in the HTML head section should take care of that. This is what
> readthedocs.io does.
> --
> Jiří Daněk
> Messaging QA
>
--
Clebert Suconic
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

tabish121@gmail.com
On 03/13/2017 04:07 PM, Clebert Suconic wrote:
> Sure.   Latest 1.x and latest 2.x.
>
>
>
> Just that it seems too much now.

Isn't that just two instances?  That doesn't seem like to much.

>
>
>
>
> On Mon, Mar 13, 2017 at 1:42 PM Jiri Danek <[hidden email]> wrote:
>
>> On Mon, Mar 13, 2017 at 6:27 PM, Clebert Suconic <
>> [hidden email]>
>> wrote:
>>
>>> I was wondering if we could / should update the docs page to only
>>> include the latest version (that is 2.0.0)... The docs are still
>>> maintained at the git, so you can always refer to the doc of the
>>> version you're using when you download.. or you can use links from
>>> github.
>>>
>> It seems strange to maintain the 1.x release stream and not have
>> documentation for it on the site. There should be at least the latest 1,x
>> and the latest 2.0 version.
>>
>> The projects whose documentation I often browse online all have previous
>> doc versions on the site, be it https://www.postgresql.org/docs/, Python
>> or
>> readthedocs.io hosted sites like http://docs.pachyderm.io/en/stable/ (see
>> the version picker at the bottom left).
>>
>> readthedocs.io sites also have a noticebar that alerts users that they are
>> browsing documentation for older release; I once raised this as feature
>> request https://issues.apache.org/jira/browse/ARTEMIS-615
>>
>>
>>> That would also make it easier for web robots (google, etc)  to index it.
>>>
>> <link href="http://www.example.com/canonical-version-of-page/"
>> rel="canonical" />
>>
>> in the HTML head section should take care of that. This is what
>> readthedocs.io does.
>> --
>> Jiří Daněk
>> Messaging QA
>>


--
Tim Bish
twitter: @tabish121
blog: http://timbish.blogspot.com/

Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

clebertsuconic
Right now we have 10. And going up.

1.0, 1.1, ....  1.5.0 1.5.1....1.5.4. 2.0

On Mon, Mar 13, 2017 at 4:37 PM Timothy Bish <[hidden email]> wrote:

> On 03/13/2017 04:07 PM, Clebert Suconic wrote:
> > Sure.   Latest 1.x and latest 2.x.
> >
> >
> >
> > Just that it seems too much now.
>
> Isn't that just two instances?  That doesn't seem like to much.
>
> >
> >
> >
> >
> > On Mon, Mar 13, 2017 at 1:42 PM Jiri Danek <[hidden email]> wrote:
> >
> >> On Mon, Mar 13, 2017 at 6:27 PM, Clebert Suconic <
> >> [hidden email]>
> >> wrote:
> >>
> >>> I was wondering if we could / should update the docs page to only
> >>> include the latest version (that is 2.0.0)... The docs are still
> >>> maintained at the git, so you can always refer to the doc of the
> >>> version you're using when you download.. or you can use links from
> >>> github.
> >>>
> >> It seems strange to maintain the 1.x release stream and not have
> >> documentation for it on the site. There should be at least the latest
> 1,x
> >> and the latest 2.0 version.
> >>
> >> The projects whose documentation I often browse online all have previous
> >> doc versions on the site, be it https://www.postgresql.org/docs/,
> Python
> >> or
> >> readthedocs.io hosted sites like http://docs.pachyderm.io/en/stable/
> (see
> >> the version picker at the bottom left).
> >>
> >> readthedocs.io sites also have a noticebar that alerts users that they
> are
> >> browsing documentation for older release; I once raised this as feature
> >> request https://issues.apache.org/jira/browse/ARTEMIS-615
> >>
> >>
> >>> That would also make it easier for web robots (google, etc)  to index
> it.
> >>>
> >> <link href="http://www.example.com/canonical-version-of-page/"
> >> rel="canonical" />
> >>
> >> in the HTML head section should take care of that. This is what
> >> readthedocs.io does.
> >> --
> >> Jiří Daněk
> >> Messaging QA
> >>
>
>
> --
> Tim Bish
> twitter: @tabish121
> blog: http://timbish.blogspot.com/
>
> --
Clebert Suconic
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

tabish121@gmail.com
On 03/13/2017 04:44 PM, Clebert Suconic wrote:
> Right now we have 10. And going up.
>
> 1.0, 1.1, ....  1.5.0 1.5.1....1.5.4. 2.0

I think John is saying the same thing I said earlier, only keep 1.5.4
and 2.0.0 as those are the latest supported releases, when 1.5.5 ships
then drop 1.5.4 ...

>
> On Mon, Mar 13, 2017 at 4:37 PM Timothy Bish <[hidden email]> wrote:
>
>> On 03/13/2017 04:07 PM, Clebert Suconic wrote:
>>> Sure.   Latest 1.x and latest 2.x.
>>>
>>>
>>>
>>> Just that it seems too much now.
>> Isn't that just two instances?  That doesn't seem like to much.
>>
>>>
>>>
>>>
>>> On Mon, Mar 13, 2017 at 1:42 PM Jiri Danek <[hidden email]> wrote:
>>>
>>>> On Mon, Mar 13, 2017 at 6:27 PM, Clebert Suconic <
>>>> [hidden email]>
>>>> wrote:
>>>>
>>>>> I was wondering if we could / should update the docs page to only
>>>>> include the latest version (that is 2.0.0)... The docs are still
>>>>> maintained at the git, so you can always refer to the doc of the
>>>>> version you're using when you download.. or you can use links from
>>>>> github.
>>>>>
>>>> It seems strange to maintain the 1.x release stream and not have
>>>> documentation for it on the site. There should be at least the latest
>> 1,x
>>>> and the latest 2.0 version.
>>>>
>>>> The projects whose documentation I often browse online all have previous
>>>> doc versions on the site, be it https://www.postgresql.org/docs/,
>> Python
>>>> or
>>>> readthedocs.io hosted sites like http://docs.pachyderm.io/en/stable/
>> (see
>>>> the version picker at the bottom left).
>>>>
>>>> readthedocs.io sites also have a noticebar that alerts users that they
>> are
>>>> browsing documentation for older release; I once raised this as feature
>>>> request https://issues.apache.org/jira/browse/ARTEMIS-615
>>>>
>>>>
>>>>> That would also make it easier for web robots (google, etc)  to index
>> it.
>>>> <link href="http://www.example.com/canonical-version-of-page/"
>>>> rel="canonical" />
>>>>
>>>> in the HTML head section should take care of that. This is what
>>>> readthedocs.io does.
>>>> --
>>>> Jiří Daněk
>>>> Messaging QA
>>>>
>>
>> --
>> Tim Bish
>> twitter: @tabish121
>> blog: http://timbish.blogspot.com/
>>
>> --
> Clebert Suconic
>


--
Tim Bish
twitter: @tabish121
blog: http://timbish.blogspot.com/

Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

clebertsuconic
Let's make the links 2.x and 1.x.  Immutable links makes it easier on
google?
On Mon, Mar 13, 2017 at 4:47 PM Timothy Bish <[hidden email]> wrote:

> On 03/13/2017 04:44 PM, Clebert Suconic wrote:
> > Right now we have 10. And going up.
> >
> > 1.0, 1.1, ....  1.5.0 1.5.1....1.5.4. 2.0
>
> I think John is saying the same thing I said earlier, only keep 1.5.4
> and 2.0.0 as those are the latest supported releases, when 1.5.5 ships
> then drop 1.5.4 ...
>
> >
> > On Mon, Mar 13, 2017 at 4:37 PM Timothy Bish <[hidden email]>
> wrote:
> >
> >> On 03/13/2017 04:07 PM, Clebert Suconic wrote:
> >>> Sure.   Latest 1.x and latest 2.x.
> >>>
> >>>
> >>>
> >>> Just that it seems too much now.
> >> Isn't that just two instances?  That doesn't seem like to much.
> >>
> >>>
> >>>
> >>>
> >>> On Mon, Mar 13, 2017 at 1:42 PM Jiri Danek <[hidden email]> wrote:
> >>>
> >>>> On Mon, Mar 13, 2017 at 6:27 PM, Clebert Suconic <
> >>>> [hidden email]>
> >>>> wrote:
> >>>>
> >>>>> I was wondering if we could / should update the docs page to only
> >>>>> include the latest version (that is 2.0.0)... The docs are still
> >>>>> maintained at the git, so you can always refer to the doc of the
> >>>>> version you're using when you download.. or you can use links from
> >>>>> github.
> >>>>>
> >>>> It seems strange to maintain the 1.x release stream and not have
> >>>> documentation for it on the site. There should be at least the latest
> >> 1,x
> >>>> and the latest 2.0 version.
> >>>>
> >>>> The projects whose documentation I often browse online all have
> previous
> >>>> doc versions on the site, be it https://www.postgresql.org/docs/,
> >> Python
> >>>> or
> >>>> readthedocs.io hosted sites like http://docs.pachyderm.io/en/stable/
> >> (see
> >>>> the version picker at the bottom left).
> >>>>
> >>>> readthedocs.io sites also have a noticebar that alerts users that
> they
> >> are
> >>>> browsing documentation for older release; I once raised this as
> feature
> >>>> request https://issues.apache.org/jira/browse/ARTEMIS-615
> >>>>
> >>>>
> >>>>> That would also make it easier for web robots (google, etc)  to index
> >> it.
> >>>> <link href="http://www.example.com/canonical-version-of-page/"
> >>>> rel="canonical" />
> >>>>
> >>>> in the HTML head section should take care of that. This is what
> >>>> readthedocs.io does.
> >>>> --
> >>>> Jiří Daněk
> >>>> Messaging QA
> >>>>
> >>
> >> --
> >> Tim Bish
> >> twitter: @tabish121
> >> blog: http://timbish.blogspot.com/
> >>
> >> --
> > Clebert Suconic
> >
>
>
> --
> Tim Bish
> twitter: @tabish121
> blog: http://timbish.blogspot.com/
>
> --
Clebert Suconic
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

Martyn Taylor
I'd prefer to keep the latest versions of docs for each minor release.  I'd
squash all the 1.5.x into just 1.5, but keep 1.0, 1.1 etc...  The 1.5 docs
may not be applicable to 1.4 due to the introduction of new features.  1.0
for example, is very different from 1.5, but we I feel we should still
provide docs for those users who have not been able to upgrade.

On a related note, (I can start a separate DISCUSS thread on this if people
prefer).

I'd like to also suggest that we stop distributing the documentation as
part of the release distribution and instead just provide links to the
latest versions.  Having the docs released as part of the binary and source
distribution, means that we need to do a full Artemis release just to get
doc changes out.  Instead I'd like to see docs either on their own release
cycle or just built periodically, housed somewhere and linked to from the
distribution.  Thoughts?

Regards
Martyn
On Mon, Mar 13, 2017 at 9:11 PM, Clebert Suconic <[hidden email]>
wrote:

> Let's make the links 2.x and 1.x.  Immutable links makes it easier on
> google?
> On Mon, Mar 13, 2017 at 4:47 PM Timothy Bish <[hidden email]> wrote:
>
> > On 03/13/2017 04:44 PM, Clebert Suconic wrote:
> > > Right now we have 10. And going up.
> > >
> > > 1.0, 1.1, ....  1.5.0 1.5.1....1.5.4. 2.0
> >
> > I think John is saying the same thing I said earlier, only keep 1.5.4
> > and 2.0.0 as those are the latest supported releases, when 1.5.5 ships
> > then drop 1.5.4 ...
> >
> > >
> > > On Mon, Mar 13, 2017 at 4:37 PM Timothy Bish <[hidden email]>
> > wrote:
> > >
> > >> On 03/13/2017 04:07 PM, Clebert Suconic wrote:
> > >>> Sure.   Latest 1.x and latest 2.x.
> > >>>
> > >>>
> > >>>
> > >>> Just that it seems too much now.
> > >> Isn't that just two instances?  That doesn't seem like to much.
> > >>
> > >>>
> > >>>
> > >>>
> > >>> On Mon, Mar 13, 2017 at 1:42 PM Jiri Danek <[hidden email]>
> wrote:
> > >>>
> > >>>> On Mon, Mar 13, 2017 at 6:27 PM, Clebert Suconic <
> > >>>> [hidden email]>
> > >>>> wrote:
> > >>>>
> > >>>>> I was wondering if we could / should update the docs page to only
> > >>>>> include the latest version (that is 2.0.0)... The docs are still
> > >>>>> maintained at the git, so you can always refer to the doc of the
> > >>>>> version you're using when you download.. or you can use links from
> > >>>>> github.
> > >>>>>
> > >>>> It seems strange to maintain the 1.x release stream and not have
> > >>>> documentation for it on the site. There should be at least the
> latest
> > >> 1,x
> > >>>> and the latest 2.0 version.
> > >>>>
> > >>>> The projects whose documentation I often browse online all have
> > previous
> > >>>> doc versions on the site, be it https://www.postgresql.org/docs/,
> > >> Python
> > >>>> or
> > >>>> readthedocs.io hosted sites like http://docs.pachyderm.io/en/
> stable/
> > >> (see
> > >>>> the version picker at the bottom left).
> > >>>>
> > >>>> readthedocs.io sites also have a noticebar that alerts users that
> > they
> > >> are
> > >>>> browsing documentation for older release; I once raised this as
> > feature
> > >>>> request https://issues.apache.org/jira/browse/ARTEMIS-615
> > >>>>
> > >>>>
> > >>>>> That would also make it easier for web robots (google, etc)  to
> index
> > >> it.
> > >>>> <link href="http://www.example.com/canonical-version-of-page/"
> > >>>> rel="canonical" />
> > >>>>
> > >>>> in the HTML head section should take care of that. This is what
> > >>>> readthedocs.io does.
> > >>>> --
> > >>>> Jiří Daněk
> > >>>> Messaging QA
> > >>>>
> > >>
> > >> --
> > >> Tim Bish
> > >> twitter: @tabish121
> > >> blog: http://timbish.blogspot.com/
> > >>
> > >> --
> > > Clebert Suconic
> > >
> >
> >
> > --
> > Tim Bish
> > twitter: @tabish121
> > blog: http://timbish.blogspot.com/
> >
> > --
> Clebert Suconic
>
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

Robbie Gemmell
What we do for Qpid is to have a central documentation/download etc
page that links to the latest release artifacts and documentation for
each component, but then also have specific pages for each component
release that includes the artifacts and docs for each specific
release. Those are also referenced from a page of current and past
releases, which is in turn referenced elsewhere on the site. This way
there is a simple area with the current docs for the current releases,
but the site still has specific pages for earlier releases that
includes their precise docs should anyone need them. We clear out the
old release content over time, e.g 2-3 years, to keep the size of the
site in check, as the docs are still available in the actual releases
themselves, which continue to be available from the dist archive,
which the site again references.

In the case where we want to update the docs of a prior release, we
can just do that on the site if so desired, though this is very rare.
The site docs for each component+version are processed from the
original release source tag when first published, and its source
becomes independant from that point unless specifically reprocessed
over the top of. Some components do link to their docs on the site,
allowing site updates to be picked up, though they are still included
in at least source form in the original release of the component.

On 15 March 2017 at 10:57, Martyn Taylor <[hidden email]> wrote:

> I'd prefer to keep the latest versions of docs for each minor release.  I'd
> squash all the 1.5.x into just 1.5, but keep 1.0, 1.1 etc...  The 1.5 docs
> may not be applicable to 1.4 due to the introduction of new features.  1.0
> for example, is very different from 1.5, but we I feel we should still
> provide docs for those users who have not been able to upgrade.
>
> On a related note, (I can start a separate DISCUSS thread on this if people
> prefer).
>
> I'd like to also suggest that we stop distributing the documentation as
> part of the release distribution and instead just provide links to the
> latest versions.  Having the docs released as part of the binary and source
> distribution, means that we need to do a full Artemis release just to get
> doc changes out.  Instead I'd like to see docs either on their own release
> cycle or just built periodically, housed somewhere and linked to from the
> distribution.  Thoughts?
>
> Regards
> Martyn
> On Mon, Mar 13, 2017 at 9:11 PM, Clebert Suconic <[hidden email]>
> wrote:
>
>> Let's make the links 2.x and 1.x.  Immutable links makes it easier on
>> google?
>> On Mon, Mar 13, 2017 at 4:47 PM Timothy Bish <[hidden email]> wrote:
>>
>> > On 03/13/2017 04:44 PM, Clebert Suconic wrote:
>> > > Right now we have 10. And going up.
>> > >
>> > > 1.0, 1.1, ....  1.5.0 1.5.1....1.5.4. 2.0
>> >
>> > I think John is saying the same thing I said earlier, only keep 1.5.4
>> > and 2.0.0 as those are the latest supported releases, when 1.5.5 ships
>> > then drop 1.5.4 ...
>> >
>> > >
>> > > On Mon, Mar 13, 2017 at 4:37 PM Timothy Bish <[hidden email]>
>> > wrote:
>> > >
>> > >> On 03/13/2017 04:07 PM, Clebert Suconic wrote:
>> > >>> Sure.   Latest 1.x and latest 2.x.
>> > >>>
>> > >>>
>> > >>>
>> > >>> Just that it seems too much now.
>> > >> Isn't that just two instances?  That doesn't seem like to much.
>> > >>
>> > >>>
>> > >>>
>> > >>>
>> > >>> On Mon, Mar 13, 2017 at 1:42 PM Jiri Danek <[hidden email]>
>> wrote:
>> > >>>
>> > >>>> On Mon, Mar 13, 2017 at 6:27 PM, Clebert Suconic <
>> > >>>> [hidden email]>
>> > >>>> wrote:
>> > >>>>
>> > >>>>> I was wondering if we could / should update the docs page to only
>> > >>>>> include the latest version (that is 2.0.0)... The docs are still
>> > >>>>> maintained at the git, so you can always refer to the doc of the
>> > >>>>> version you're using when you download.. or you can use links from
>> > >>>>> github.
>> > >>>>>
>> > >>>> It seems strange to maintain the 1.x release stream and not have
>> > >>>> documentation for it on the site. There should be at least the
>> latest
>> > >> 1,x
>> > >>>> and the latest 2.0 version.
>> > >>>>
>> > >>>> The projects whose documentation I often browse online all have
>> > previous
>> > >>>> doc versions on the site, be it https://www.postgresql.org/docs/,
>> > >> Python
>> > >>>> or
>> > >>>> readthedocs.io hosted sites like http://docs.pachyderm.io/en/
>> stable/
>> > >> (see
>> > >>>> the version picker at the bottom left).
>> > >>>>
>> > >>>> readthedocs.io sites also have a noticebar that alerts users that
>> > they
>> > >> are
>> > >>>> browsing documentation for older release; I once raised this as
>> > feature
>> > >>>> request https://issues.apache.org/jira/browse/ARTEMIS-615
>> > >>>>
>> > >>>>
>> > >>>>> That would also make it easier for web robots (google, etc)  to
>> index
>> > >> it.
>> > >>>> <link href="http://www.example.com/canonical-version-of-page/"
>> > >>>> rel="canonical" />
>> > >>>>
>> > >>>> in the HTML head section should take care of that. This is what
>> > >>>> readthedocs.io does.
>> > >>>> --
>> > >>>> Jiří Daněk
>> > >>>> Messaging QA
>> > >>>>
>> > >>
>> > >> --
>> > >> Tim Bish
>> > >> twitter: @tabish121
>> > >> blog: http://timbish.blogspot.com/
>> > >>
>> > >> --
>> > > Clebert Suconic
>> > >
>> >
>> >
>> > --
>> > Tim Bish
>> > twitter: @tabish121
>> > blog: http://timbish.blogspot.com/
>> >
>> > --
>> Clebert Suconic
>>
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

clebertsuconic
In reply to this post by Martyn Taylor
On Wed, Mar 15, 2017 at 6:57 AM, Martyn Taylor <[hidden email]> wrote:
> I'd prefer to keep the latest versions of docs for each minor release.  I'd
> squash all the 1.5.x into just 1.5, but keep 1.0, 1.1 etc...  The 1.5 docs
> may not be applicable to 1.4 due to the introduction of new features.  1.0
> for example, is very different from 1.5, but we I feel we should still
> provide docs for those users who have not been able to upgrade.

Users can refer to the docs on github or on the downloaded package
also. We could even add a note to where to relate the docs if you're
on a older version.


2 years from now... 2.1, 2.2, 2.3... .the list will only grow...


We're even encouraged to archive older downloads from apache
guidelines.. I believe Tim Bish did some cleanup on ActiveMQ and
Artemis last year for that reason.


>
> On a related note, (I can start a separate DISCUSS thread on this if people
> prefer).
> I'd like to also suggest that we stop distributing the documentation as
> part of the release distribution and instead just provide links to the
> latest versions.  Having the docs released as part of the binary and source
> distribution, means that we need to do a full Artemis release just to get
> doc changes out.  Instead I'd like to see docs either on their own release
> cycle or just built periodically, housed somewhere and linked to from the
> distribution.  Thoughts?

I would keep the docs on the release the way it is, for the reason I
mentioned before.. we wouldn't keep 1.0, 1.1. .... 1.N, 2.N on the
website.

But then minor updates could go to the website right away without
requiring a release just for that.

We could even add a link for a more updated documentation visit us @
.. (Link goes here).
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

andytaylor
Personally, I would prefer a separate repo for the docs, its fine to have
versions linked to a release but then they are set in stone. Docs are
usually the last thing to get written and sometimes rushed or maybe not
even in time for a release. If they were in a separate repo you could still
spend time improving them as a separate effort, adding missing info, fixing
mistakes etc. we could still ship them with a release if we wanted but also
allow for further updates after then. We could also have 2 streams in 1 for
1.5 and 1 for 2.0.

Andy

On 15 March 2017 at 13:56, Clebert Suconic <[hidden email]>
wrote:

> On Wed, Mar 15, 2017 at 6:57 AM, Martyn Taylor <[hidden email]> wrote:
> > I'd prefer to keep the latest versions of docs for each minor release.
> I'd
> > squash all the 1.5.x into just 1.5, but keep 1.0, 1.1 etc...  The 1.5
> docs
> > may not be applicable to 1.4 due to the introduction of new features.
> 1.0
> > for example, is very different from 1.5, but we I feel we should still
> > provide docs for those users who have not been able to upgrade.
>
> Users can refer to the docs on github or on the downloaded package
> also. We could even add a note to where to relate the docs if you're
> on a older version.
>
>
> 2 years from now... 2.1, 2.2, 2.3... .the list will only grow...
>
>
> We're even encouraged to archive older downloads from apache
> guidelines.. I believe Tim Bish did some cleanup on ActiveMQ and
> Artemis last year for that reason.
>
>
> >
> > On a related note, (I can start a separate DISCUSS thread on this if
> people
> > prefer).
> > I'd like to also suggest that we stop distributing the documentation as
> > part of the release distribution and instead just provide links to the
> > latest versions.  Having the docs released as part of the binary and
> source
> > distribution, means that we need to do a full Artemis release just to get
> > doc changes out.  Instead I'd like to see docs either on their own
> release
> > cycle or just built periodically, housed somewhere and linked to from the
> > distribution.  Thoughts?
>
> I would keep the docs on the release the way it is, for the reason I
> mentioned before.. we wouldn't keep 1.0, 1.1. .... 1.N, 2.N on the
> website.
>
> But then minor updates could go to the website right away without
> requiring a release just for that.
>
> We could even add a link for a more updated documentation visit us @
> .. (Link goes here).
>
Reply | Threaded
Open this post in threaded view
|

Re: [DISCUSS] Single version docs on Artemis

clebertsuconic
Like Francesco just committed a doc changed on mapped journal. Mapped
Journal is on 2.0.0 but the docs are out dated.

On Wed, Mar 15, 2017 at 2:13 PM, Andy Taylor <[hidden email]> wrote:

> Personally, I would prefer a separate repo for the docs, its fine to have
> versions linked to a release but then they are set in stone. Docs are
> usually the last thing to get written and sometimes rushed or maybe not
> even in time for a release. If they were in a separate repo you could still
> spend time improving them as a separate effort, adding missing info, fixing
> mistakes etc. we could still ship them with a release if we wanted but also
> allow for further updates after then. We could also have 2 streams in 1 for
> 1.5 and 1 for 2.0.
>
> Andy
>
> On 15 March 2017 at 13:56, Clebert Suconic <[hidden email]>
> wrote:
>
>> On Wed, Mar 15, 2017 at 6:57 AM, Martyn Taylor <[hidden email]> wrote:
>> > I'd prefer to keep the latest versions of docs for each minor release.
>> I'd
>> > squash all the 1.5.x into just 1.5, but keep 1.0, 1.1 etc...  The 1.5
>> docs
>> > may not be applicable to 1.4 due to the introduction of new features.
>> 1.0
>> > for example, is very different from 1.5, but we I feel we should still
>> > provide docs for those users who have not been able to upgrade.
>>
>> Users can refer to the docs on github or on the downloaded package
>> also. We could even add a note to where to relate the docs if you're
>> on a older version.
>>
>>
>> 2 years from now... 2.1, 2.2, 2.3... .the list will only grow...
>>
>>
>> We're even encouraged to archive older downloads from apache
>> guidelines.. I believe Tim Bish did some cleanup on ActiveMQ and
>> Artemis last year for that reason.
>>
>>
>> >
>> > On a related note, (I can start a separate DISCUSS thread on this if
>> people
>> > prefer).
>> > I'd like to also suggest that we stop distributing the documentation as
>> > part of the release distribution and instead just provide links to the
>> > latest versions.  Having the docs released as part of the binary and
>> source
>> > distribution, means that we need to do a full Artemis release just to get
>> > doc changes out.  Instead I'd like to see docs either on their own
>> release
>> > cycle or just built periodically, housed somewhere and linked to from the
>> > distribution.  Thoughts?
>>
>> I would keep the docs on the release the way it is, for the reason I
>> mentioned before.. we wouldn't keep 1.0, 1.1. .... 1.N, 2.N on the
>> website.
>>
>> But then minor updates could go to the website right away without
>> requiring a release just for that.
>>
>> We could even add a link for a more updated documentation visit us @
>> .. (Link goes here).
>>



--
Clebert Suconic