Improving Documentation for new OpenStack Contributors

I think we’re starting to see too much friction and pain from contributors to OpenStack plugins, drivers, extensions: a lot is going on and joining the community feels like boarding a bullet train while it’s running at full speed. We’ve been doing a good job pulling people in the OpenStack community and educate them with our tools, processes especially for contributors to the Compute, Storage, Networking pieces of OpenStack; there are margins to improve life for “casual” contributors and newcomers in general.

The main problem I think is that we’ve been treating all developers like they all have the same amount of dedication to the collaboration effort. We’ve been asking every person contributing to OpenStack to act the same way, whether they were fixing a small bug in Keystone or refactoring Neutron’s code: same gerrit review workflow, same process for blueprints/specs. We assumed always that anybody at any given time had the same level of knowledge of deadlines and recent changes to the processes. We are requiring people with radically different objectives and set of incentives to know and do the same things. I think this is starting to become too much of a problem for the community. We are already having conversations about this (split drivers, Neutron incubator, refocus summit, modify the legal requirements) and will continue discussing in Paris.

The one thing that we should start improving immediately is the documentation for new contributors. New contributors have lots of resources available like the Welcome Guide,, lots of wiki pages of varying degree of correctness and quality, tips and tricks on blog posts, upcoming video series, IRC support and Upstream Training. Based on what I hear from some, they struggle because these are in different places and owned by different people. A place where this content is shown in a more coherent way would be a great improvement.

There are two efforts to improve various pieces of documentation: the Documentation program wants to redesign the Docs portal, and a new portal is being designed for developers of applications based on OpenStack. The Documentation program is not responsible for developers’ content on the Docs portal, it simply hosts the materials produced directly by the programs. While we wait for a redesign of the Documentation portal, I think we can start by fixing the wiki pages. With the help of a taxonomy produced by volunteer Katherine Cranford and Foundation’s staff Shari Mahrdt, we’ll give a bit more structure to the OpenStack wiki. Stay tuned for more details.