Open Stack

Le 2014-06-20 09:18, Tom Fifield a écrit :
> On 20/06/14 15:13, Gauvain Pocentek wrote:
>> We've received several bug reports about the auth_strategy nova 
>> option
>> missing from our install procedure these last few days. These bugs 
>> are
>> reported against the trunk doc, by people installing icehouse. The 
>> doc
>> is in fact correct, both in trunk (the default for this option in 
>> juno
>> has changed and we don't need to set it anymore), and in the icehouse
>> branch (where the option is set up in the procedure).
>> 
>> Would it be possible to mark the pages in the trunk/ subdirectory of
>> docs.o.org as "in progress" or "unstable", or anything that would
>> explicitly tell the user that he might not be reading the correct 
>> page?
>> We already have "juno" in the install-guide and config-ref titles, 
>> but I
>> don't think it's visible enough.
> 
> 
> This is indeed a problem.
> 
> I find it's quite similar to our Critical bug "Clearly mark outdated
> doc pages" https://bugs.launchpad.net/openstack-manuals/+bug/1191447
> 
> 
> I've proposed a patch @ https://review.openstack.org/#/c/101428/ that
> will make it more obvious that trunk is juno, but I don't think it
> solves the problem.

Users following the guide will very soon realize that this is not what 
they want with this patch. IMO that's a good thing. With the current 
trunk/, I'm quite sure that people end up thinking "the doc is not good, 
I can't get this thing to work". We really don't want them to think that 
:)

When starting this thread I had the django documentation website in 
head. They have a relatively visible warning on the top of dev version 
pages: https://docs.djangoproject.com/en/dev/ . If Tom's patch is not 
enough, we could look into implementing a similar feature.

Gauvain