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 <[email protected]> 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 <[email protected]> > 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 <[email protected]> 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 <[email protected]> >> > 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 <[email protected]> >> wrote: >> > >>> >> > >>>> On Mon, Mar 13, 2017 at 6:27 PM, Clebert Suconic < >> > >>>> [email protected]> >> > >>>> 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 >>
