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 <[email protected]> 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 __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
