Upload
anne-gentle
View
108
Download
1
Tags:
Embed Size (px)
DESCRIPTION
An overall description of the OpenStack documentation program's processes and vision.
Citation preview
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.