Open Stack

On 09/16/2014 09:49 AM, Ryan Brown wrote:.
> 
> (From Zane's other message)
>> <snip>
>> I think the first supported release is probably the right information
> to add.
>> <snip>
> 
> I feel like for anything with nonzero upgrade effort (and upgrading your
> openstack install takes significantly more than 0 effort units) you can
> never assume everyone is running the latest (or even a recent) revision.
> That's why projects often host docs versions *way* back.
> 
> The SQLAlchemy project hosts docs back to 2012[1] and also has latest[2]
> docs that are updated continuously. I think the way to support the most
> use cases would be to have docs for each release as well as continue to
> have CI update docs.
> 
> For a URL structure I could see docs.o.o/developer/heat/latest and
> d.o.o/heat/<VER> where <VER> can be either a semver release (2014.2,
> etc) or a release name (icehouse, havana, etc). The strategy SQLA and
> other projects use is to feature a release date prominently at the top
> of the page, so users can look and say "Oh, Juno isn't released yet, so
> this feature won't be in my Icehouse cloud".
> 
> [1] http://docs.sqlalchemy.org/en/rel_0_6/core/index.html
> [2] http://docs.sqlalchemy.org/en/latest/core/index.html
> 
> 

Also most projects that use readthedocs.org have a dropdown on every
docs page that link to that page at different releases. I think it would
greatly improve discoverability of documentation for prior releases.

Sorry for doubling up messages,
-- 
Ryan Brown / Software Engineer, Openstack / Red Hat, Inc.