Open Stack

On Thu, Mar 24, 2016 at 07:14:35AM +1000, Lana Brindley wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA256
> 
> Hi Mike, and sorry I missed you on IRC to discuss this there. That said, I think it's great that you took this to the mailing list, especially seeing the conversation that has ensued.
> 
> More inline ...
> 
> On 24/03/16 01:06, Mike Perez 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.
> 
> As Steve pointed out, these now have solid plans to go in. That was because both projects opened a conversation with us and we worked with them over time to give them the docs they required.
> 
> > 
> > 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".
> 
> I agree, but it's a great place to start. In fact, I've just merged a change to the Docs Contributor Guide (on the back of a previous mailing list conversation) that explicitly states this:
> 
> http://docs.openstack.org/contributor-guide/quickstart/new-projects.html
> 
> > 
> > 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.
> 
> Which is exactly why we're very selective. Sadly, documenting every big tent project's install process is no small task.

I'd love to have some sort of plugin system, where teams can be
responsible for their own install guide repo, with a single line in the
RST for the install guide to have it include the repo in the build.

// jim

> 
> > 
> > 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.
> 
> I agree. This has been an issue for several cycles now, but with all our RST conversions now (mostly) behind us, I feel like we can dedicate the Newton cycle to improving how we do things. Exactly how that happens will need to be determined by the docs team in the Austin Design Summit, and I strongly suggest you intend to attend that session once we have it scheduled, as your voice is important in this conversation.
> 
> Lana
> 
> - -- 
> Lana Brindley
> Technical Writer
> Rackspace Cloud Builders Australia
> http://lanabrindley.com
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v2
> Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
> 
> iQEcBAEBCAAGBQJW8wc7AAoJELppzVb4+KUywYMIAMr78Gw+zPp3LXyqxkQFPs9y
> mo/GJrfQ9OLD6CXpKSxcmvnuaHP1vHRrXPqkE02zb6YTOxV3C3CIW7hf023Dihwa
> uED5kL7DrkTO+xFrjClkVRpKit/ghWQ3By/V9yaYjgWQvvRy3/Y+dvjZHnrDDHE1
> rIxbU4PVZ0LPTxI7nNy71ffxFXW2Yn9Pl6EJnVm/iu9R+BNfRHgQ3kdqalG+Ppat
> 9tZIGpxzi5/dTS9dTf5zN2GqYzYoDR8J6C/O/ojWyOjwcycvqWH0XboV7usLLMR8
> 77RB/Ob8WszpbHZ6+yJF3P9hJhwhFXs8UJFcapkwaMy7wu8Lt0+etgC8nPDFj9I=
> =hsaE
> -----END PGP SIGNATURE-----
> 
> __________________________________________________________________________
> OpenStack Development Mailing List (not for usage questions)
> Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev