On Tue, Sep 25, 2018 at 3:02 PM Gregory Farnum <gfarnum@xxxxxxxxxx> wrote: > > On Tue, Sep 25, 2018 at 4:32 AM Lenz Grimmer <lgrimmer@xxxxxxxx> wrote: > > > > Hi all, > > > > thanks Noah and Neha for raising this topic. > > > > On 09/25/2018 10:26 AM, Sebastian Wagner wrote: > > > > > Am 25.09.2018 um 01:48 schrieb Noah Watkins: > > >> I was googling this morning for random ceph terminology, as one does, > > >> and noticed that the top 5 results often included some deep cuts like > > >> kraken/bobtail/giant etc... it'd be really nice to have some sort of > > >> visual cue about the freshness of the docs being viewed. > > >> > > >> Following up on Neha's comments from this morning's meeting regarding > > >> documentation improvements, Neha and I brainstormed some ideas this > > >> afternoon and tossed them in an etherpad: > > >> > > >> https://pad.ceph.com/p/Ceph_Documentation > > >> > > >> Please feel free to add / edit / comment. > > > > > > +1 for adding a robots.txt. Having an outdated documentation in the top > > > spot of search results has led to some confusion in the past. > > > > I agree. Ideally, search engine results should always refer to the last > > publicly released version, not the development branch or outdated > > versions (to avoid confusion). > > > > However, the current documentation structure makes this somewhat > > cumbersome, as we would have to update robots.txt every time a new major > > release has been published, if I'm not mistaken. > > > > This also applies when visiting docs.ceph.com directly - by default, it > > should redirect to the documentation of the current stable release - > > currently it points to "master" (the development version). > > This is interesting, because there's a conflict between using the > "stable" and current "master" branches in our docs — a lot of > documentation changes are actually general improvements which apply to > all our live releases, not just the master branch they go in on. > > Should we start tagging documentation PRs for backport? We backport docs with code changes for ceph-volume. If components are getting backported without its corresponding doc update it is a bug (otherwise why have per-release versions of docs). > > > > > At a minimum, I think it should be more visible to the reader that > > he/she is looking at an either outdated or work in progress variant of > > the docs. > > > > Ideally, there should be an easy way to switch between different > > available versions. > > > > Would it make sense to make use of a service like readthedocs.io for > > hosting the documentation? We're using it for the openATTIC > > documentation [1] and it already provides built-in functionality to > > define which version will be displayed by default, a switch to select > > different versions or a link to edit the current document (on BitBucket > > in our case, but github likely works, too). Oh, and multiple document > > formats ;) > > > > Lenz > > > > https://docs.openattic.org/en/latest/ > > > > -- > > SUSE Linux GmbH - Maxfeldstr. 5 - 90409 Nuernberg (Germany) > > GF:Felix Imendörffer,Jane Smithard,Graham Norton,HRB 21284 (AG Nürnberg) > >
