OpenStack DocumentationProjects and Process

OpenStack Docs Boot Camp

Anne Gentle

September 2013

®

Schedule

Monday• Anne Gentle, Documentation Program Overview• Jim Blair, Infrastructure and Docs• David Cramer, DocBook, Maven• Tom Fifield, Autodoc• You, and you, and you, Unconference topics

Tuesday• Diane Fleming, API Docs and WADL• Steve Gordon, Publican publishing• Shaun McCance, Install docs• Nick Chase, How to Contribute to Docs• You, and you, and you, Unconference topics

®

Expectations

• Listen but also ask questions• Be real-time• Try the labs• Do calls in breakout rooms• Write an unconference topic note any time you think of one• Show appreciation to David, Nick, and Nermina at Mirantis for

being awesome hosts!

®

I Believe in Community

Flickr: seier+seier

®

I am… a Content Stacker

•OpenStack – Open Source Cloud Computing

•Rackspace – Fanatical Support in all we do

®

Our Hero

Not always a technical writer

Wanting to make an impact

▪ Writers are user advocates

▪ Need a plan and execution

®

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 – real-time, in person Summit every six months.

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

®

Background and History

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

(Rackspace 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• Networks – Neutron• Volume service - Cinder

®

OpenStack Projects - Integrated

•Metering – Ceilometer•Orchestration – Heat•Libraries – Oslo

®

OpenStack Projects – Incubated or Applying

Incubating:•Databases – Trove•Bare metal – Ironic

Applying:•Hadoop (NoSQL) – Savannah•Queuing – Marconi

®

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 – What do we do at the Design Summit?•Blueprints and discussion at Design Summit•Documentation track• Implementation of blueprints – example, api.openstack.org design and implementation

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

®

OpenStack Documentation Processes –Launchpad•Bug logging•Bug triaging•Bug assigning

®

OpenStack Documentation Processes –git.openstack.org (Github) and Gitopenstack/openstack-manuals, openstack/operations-guide

Cloud Administrators Guide

OpenStack Configuration Reference

OpenStack High Availability Guide

OpenStack Virtual Machine Image Guide

OpenStack Installation Guide

OpenStack Networking Administration Guide

OpenStack Security Guide

OpenStack Training Guide

OpenStack End User Guide

OpenStack Admin User Guide

OpenStack Operations Guide

API doc reposopenstack/api-site – api.openstack.org/api-ref.html, API Quick Start, Compute API Programming Guide

openstack/object-api

openstack/compute-api

openstack/netconn-api

openstack/identity-api

openstack/image-api

openstack/volume-api

openstack/database-api

®

OpenStack Documentation Processes – Gerrit (review.openstack.org) and Jenkins• Automated publishing process with Jenkins jobs and Gerrit reviews

®

OpenStack Documentation Processes – Book Sprints, a book in a week

®

Where Documentation Processes Diverge from Development Processes•Does not track milestone releases yet•Translation automation being set up

®

OpenStack Documentation

•Who are our audiences?•What are their tasks and jobs?•How can we focus doc efforts?

®

Persona FindingsO

mar

• Title: Operations Support Specialist, Puppet Developer, Chef Developer, System Administrator, possibly devops in title (rare)

• Duties: Provide operational support for cloud solutions, build and maintain clouds, monitor cloud, build clouds

Ang

ie • Title: Software Engineer, Rails Developer, Java Developer, Python Developer, PHP Developer

• Duties: Design and implement a new cloud solution for application, prototype the solution using OpenStack cloud APIs (SDK if needed)

Jeff • Title: Cloud Architect,

Systems Analyst, IT Consultant

• Duties: Design and implement the new cloud solution, prototype the solution

similar

22

®

How We Learn*

• Little or no experience.• Needs rules, step-by-

step instructions.

Novice

• Tries tasks independently, some difficulty troubleshooting.

• Wants information fast, but lacks holistic understanding.

Advanced Beginner

• Acts on long-term goals and planning and can troubleshoot independently.

• Understands mechanics, but wants expert understanding.

Competent

• Wants to understand larger framework, frustrated by overly simple information.

• Learns from other’s experiences.

Proficient

• Primary source of knowledge at company and continually seeks better methods.

• Following prescribed rules or step-by-step degrades performance.

Expert

23

*Studied by Dreyfus & Dreyfus, applied across many industries including nursing and computer software.

®

Novice and Adv. Beginner Users = Casual Users

• Wants to be led• Intimidated, nervous• Afraid of failure• Difficulty troubleshooting

Omar’s Concerns

• Consistency, small chunks to ease recall

• Walkthroughs, tours• Embedded help• Getting Started Guides

Omar’s Solutions

Just Write Click24

®

Competent, Proficient, Expert = Power Users

• Frustrated by over-simplified information• Seek shortcuts, tips, tricks, and

examples• Troubleshooting, but seeks starting

points• Serving as resource to others

Jeff’s Concerns*

• Conceptual and planning topics• Searchable knowledge base• Online communities• “Getting Results” Guides with working

examples and designs• Reference Guides

Jeff’s Solutions

Just Write Click25

*Applies to Angie too.

®

Doc Team Composition

All OpenStack community members

90+9+1 = 100 = online participation inequality

One percenters = OpenStack-doc-core

Flickr: jurvetson

®

Analytics: Sept 2012 Contributors

Doh. Release date.

Hey! Release date!

®

Analytics: Sept. 2013 contributors

We are here.

®

Progress and big wins

•40+ Compute API Extensions•66% Site visitors stay instead of leaving

•100 Doc patches and reviews a month

•1500+ Configuration options •150,000 Unique pageviews a week

®

Future vision

• Making OpenStack accessible.• Providing standard shared API content.• Creating an API try-it-out sandbox. • Building community around doc tooling.• Encouraging and prioritizing translations.• Improving doc contribution workflow. • Improving doc/dev collaboration.• Integrating with ask.openstack.org.• You tell me.

®

®

Questions with Answers

How can I get on the openstack-core-docs team?Do lots of reviews at http://review.openstack.org for the docs repos. 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.