Open Stack

Excerpts from Russell Bryant's message of 2016-03-23 15:25:57 -0400:
> On Wed, Mar 23, 2016 at 11:06 AM, Mike Perez <thingee at gmail.com> wrote:
> 
> > Hey all,
> >
> > I've been talking to a variety of projects about lack of install guides.
> > This
> > came from me not having a great experience with trying out projects in the
> > big
> > tent.
> >
> > Projects like Manila have proposed install docs [1], but they were rejected
> > by the install docs team because it's not in defcore. One of Manila's
> > goals of
> > getting these docs accepted is to apply for the operators tag
> > ops:docs:install-guide [2] so that it helps their maturity level in the
> > project
> > navigator [3].
> >
> > Adrian Otto expressed to me having the same issue for Magnum. I think it's
> > funny that a project that gets keynote time at the OpenStack conference
> > can't
> > be in the install docs personally.
> >
> > As seen from the Manila review [1], the install docs team is suggesting
> > these
> > to be put in their developer guide.
> >
> > I don't think this is a great idea. Mainly because they are for developers,
> > operators aren't going to be looking in there for install information.
> > Also the
> > Developer doc page [4] even states "This page contains documentation for
> > Python
> > developers, who work on OpenStack itself".
> >
> > The install docs team doesn't want to be swamped with everyone in big tent
> > giving them their install docs, to be verified, and eventually likely to be
> > maintained by the install docs team.
> >
> > However, as an operator when I go docs.openstack.org under install guides,
> > I should know how to install any of the big tent projects. These are
> > accepted
> > projects by the Technical Committee.
> >
> > Lets consider the bigger picture of things here. If we don't make this
> > information accessible, projects have poor adoption and get less feedback
> > because people can't attempt to install them to begin reporting bugs.
> >
> > Proposal: if the install docs team doesn't want them in the install docs
> > repo
> > and instead to live in tree of the project itself before it's in defcore,
> > can
> > we at least make the install guides for all big tent projects accessible
> > at docs.openstack.org under install guides?
> >
> >
> > [1] - https://review.openstack.org/#/c/213756/
> > [2] -
> > http://git.openstack.org/cgit/openstack/ops-tags-team/tree/descriptions/ops-docs-install-guide.rst
> > [3] - http://www.openstack.org/software/releases/liberty/components/manila
> > [4] - http://docs.openstack.org/developer/openstack-projects.html
> >
> 
> ​FWIW, the same issue applies to other official docs.  In particular, I'm
> thinking of the networking guide.
> 
> http://docs.openstack.org/liberty/networking-guide/
> 
> The networking guide is *fantastic*, but it's limited to covering only
> ML2+OVS and ML2+LB.  Coverage for other backends is currently considered
> out of scope, leaving no official place to put equivalent documentation
> except in dev docs.
> 
> We got pushback on documenting OVN there, so we've been putting everything
> in our dev docs, instead.  For example:
> 
> http://docs.openstack.org/developer/networking-ovn/install.html
> http://docs.openstack.org/developer/networking-ovn/refarch.html
> 
> ​It'd be nice to have somewhere else to publish these operator-oriented
> docs.
> 

Yes, I think we need a place between "The" manual and the
contributor-focused docs. I could see room for all sorts of smaller
and more focused guides but we need to make them discoverable.

Doug