Open Stack

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.

-- 
Russell Bryant
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160323/6df201ff/attachment.html>