Open Stack

+1 on making sure every project *has* these pieces; standardizing them is less of a priority in my mind.

Personally, I prefer very thorough release notes published with the documentation (a la http://docs.openstack.org/developer/horizon/#release-notes ), as it gives a more thorough overview than just a changelog. In those release notes I like to highlight 3 key areas:

*         release highlights (features and fixes)

*         known issues

*         backwards-incompatible changes (if there are any).

Covering those three areas makes sure people upgrading really know what they're getting. I'm already working on the Folsom release notes for Horizon.

I do like the idea of having a migration guide published for each version, though. I think that'd be helpful in making people mindful of what backwards-incompatible changes they've made in a release cycle.

Though many (if not all) of the projects do have some form of installation guide already they could all be better. The problem there is that there are so many ways to install/setup/configure that writing a single guide is impractical. I think it's better to have a concise summary of installation/deployment concerns that people should be made aware of, and then to provide sort of a "sample" or "reference" installation guide as a companion to that documentation.

Great suggestions!


-          Gabriel

From: Joshua Harlow [mailto:harlowja at yahoo-inc.com]
Sent: Friday, August 31, 2012 10:26 AM
To: OpenStack Development Mailing List
Subject: [openstack-dev] Question on component docs

Hi all,

I was wondering if we could figure out a way to standardize on each project having a set of docs in certain locations that would be used for the following.


  1.  Knowing what the changes were for a given release (ie a 'changelog' file)
  2.  Possibly a 'migration' file that would explain how to migrate from version N-1
  3.  Docs on how to install/setup/configure for the current code (kept up to date locally, not in devstack...)
Right now it seems like some of these are in rst (for docs.openstack.org), some are in devstack/rst (the nitty gritty about how to install), some are nonexistent (ie the changelog?). It would seem like each project should have the same set of files in the same locations for all 3 of these without having to refer to X other projects (devstack, the docs pages...).

What do people think?
Is something like this feasible, desired (it'd be nice for me to not have to look at devstack to know how stuff is installed)?
Thoughts?

-Josh

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20120831/8094e87b/attachment-0001.html>