OpenStack DocumentationProjects and Process

OpenStack Documentation in the Open

Anne Gentle at the July 2012 OpenStack Austin Meetup

®

Goals (Big, Hairy, Audacious)• Increase OpenStack adoption. • Provide OpenStack support. • Be strategic, collaborative, and open.• Provide truth and trust. • Achieve business objectives.

®

What is OpenStack?

• OpenStack is a global collaboration of developers and cloud computing technologists producing the open standard cloud computing platform for both public and private clouds.

• The project aims to deliver solutions for all types of clouds by being simple to implement, massively scalable, and feature rich.

• The technology consists of a series of interrelated projects delivering various components for a cloud infrastructure solution.

®

OpenStack Principles

• Open development model – Apache 2.0 license, Contributors agreement.

• Open design process – Design Summit every six months.

• Open community – Resources dedicated to active developer and user community. Open processes required.

®

Where were we? How has this effort evolved?

• Started September 2010 and did a content audit. Found:– Two projects: Compute and Object Storage projects (Cloud Servers and Cloud

Files)– Two audiences: Python dev docs (in RST) and REST API “Dev Guides” (in

DocBook)

• Added operations audience. • Added HTML and comments with the Bexar release Feb 2011.

Bam. Site Launch.

Flickr: andy_c

®

OpenStack Projects - Core

• Compute – Nova• Storage – Swift• Identity service - Keystone• Image service - Glance• OpenStack Dashboard - Horizon• Network Connectivity service – Quantum• Volume service - Cinder

®

OpenStack Release Process

• Planning– Design Summits– Blueprints

• Implementation

• QA

• Release – Release milestones– Release Candidate Freeze– Feature Freeze Exception– Release naming– Release numbering

®

OpenStack Documentation Processes – Design Summit• Blueprints and discussion at Design Summit

• Implementation of blueprints – example, api.openstack.org

• Current blueprints found at https://blueprints.launchpad.net/openstack-manuals

®

OpenStack Documentation Processes –Launchpad• Bug logging

• Bug triaging

• Bug assigning

• Core documentation team – monthly meetings

®

OpenStack Documentation Processes –Github and GitGithub repositories store admin guides and

API guides

openstack/openstack-manuals

Contains:– Compute admin manual– Storage admin manual– API Quick Start– Compute API Programmer’s Guide– Install guide for Compute– Network connectivity (Quantum) admin

manual

One dev guide each (plus WADLs):

openstack/object-api

openstack/compute-api

openstack/netconn-api

openstack/identity-api

openstack/image-api

®

OpenStack Documentation Processes – Gerrit and Jenkins• Automated publishing process with Jenkins jobs and Gerrit reviews

®

Where Documentation Processes Diverge from Development Processes• Does not track milestone releases yet• Translation not yet set up, prototype in the works. See https://gist.github.com/2969337.

®

Doc Team Composition

All OpenStack community members

One percenters = OpenStack-doc-core

Badge Wearers• AT&T • IBM• Nebula• Nicira• Nimbis Services• Nuage• Rackspace• RedHat

Grad Students• University of

Melbourne• University of

Tokyo

Flickr: jurvetson

®

Progress and big wins

•20+ Extensions documented•66% Site visitors stay instead of leaving

•100 Doc patches and reviews a month

•726 Configuration options •10,000 Unique visitors a week at docs.openstack.org

®

Future vision

• Making OpenStack accessible.• Creating proof-of-concepts for shared API content and

API try-it-out.• Building community around doc tooling.• Exploring translations.• Improving doc contribution workflow. • Improving doc/dev collaboration.• Investigating need for a knowledge base.• Prioritizing deployment and operation documentation.

®

Questions with Answers

How can I get on the openstack-core-docs team?Do lots of reviews at http://review.openstack.org for the openstack-manuals project. Triage bugs and log doc bugs at http://bugs.launchpad.net/openstack-manuals. We’ll discuss on the openstack-docs-core mailing list and then invite you.

How should I find doc work that needs to be done on a particular project?

Refer to http://bugs.launchpad.net/openstack-manuals and look for Wishlist for tasks, or any doc bug can be picked up as a work item. We also track few blueprints which may need someone to work on, though doc bugs are probably the best first place to look

How do I know who should do reviews of my document changes?

Anne Gentle, the doc coordinator, or anyone on the openstack-doc-core team can help you identify reviewers, or you can also check the doc bug and ask the reporter to review the changes by adding their name to the reviewers list.