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). 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)
Attachment:
signature.asc
Description: OpenPGP digital signature
