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? > > 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) >
