2. ®
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
3. ®
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!
5. ®
I am… a Content Stacker
•OpenStack – Open
Source Cloud
Computing
•Rackspace – Fanatical
Support in all we do
6. ®
Our Hero
Not always a
technical writer
Wanting to make
an impact
▪ Writers are user
advocates
▪ Need a plan and
execution
7. ®
Goals (Big, Hairy,
Audacious)
• Increase OpenStack adoption.
• Provide OpenStack support.
• Be strategic, collaborative, and open.
• Provide truth and trust.
• Achieve business objectives.
8. ®
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.
9. ®
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.
10. ®
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
11. ®
OpenStack Projects - Core
• Compute – Nova
• Storage – Swift
• Identity service - Keystone
• Image service - Glance
• OpenStack Dashboard - Horizon
• Networks – Neutron
• Volume service - Cinder
15. ®
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
17. ®
OpenStack Documentation Processes –
git.openstack.org (Github) and Git
openstack/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 repos
openstack/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
18. ®
OpenStack Documentation Processes –
Gerrit (review.openstack.org) and Jenkins
• Automated publishing process with Jenkins jobs and Gerrit reviews
22. ®
Persona FindingsOmar
• 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
Angie
• 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 solutionsimilar
22
23. ®
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.
24. ®
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 Click
24
25. ®
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 Click
25
*Applies to Angie too.
26. ®
Doc Team Composition
All OpenStack
community members
90+9+1 = 100 =
online participation
inequality
One percenters =
OpenStack-doc-core
Flickr: jurvetson
29. ®
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
30. ®
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.
32. ®
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.
Notas del editor
I am a content stacker at Rackspace, here’s where I think we’re going
So where are we today? This is computer scientist Barbie. When Mattel surveyed thousands of little girls asking what careers they are interested in, they said computer scientist – and also journalist! Guess what, that is what we are heading towards today. While news delivery and sourcing is changing, actual professional journalism is still in demand. The same goes for professional technical writing – we report on the indepth stories behind the technology to help everyone understand what they need to know. I believe we can be heroes of the technology world by working with social web techniques.
I was the lead for AT&T’s private cloud Increase adoption by driving usage and deployments – I was the first point of contact for AT&T’s cloud entry. I trained Huawei on Object Storage. People often contact me first.Provide support with docs and comments. In fact, docs.openstack.org gets about 10,000 unique visitors a week.Be strategic, collaborative, and open with documentation. (That’s the BHAG!) I’ve bet my career on this approach.Hard as you might think with fast-moving code.Business objectives vary depending on their launch, whether it’s public or private, consulting or increasing adoption, or creating a standard.
There are now seven OpenStackprojects, six of which have APIs (the Dashboard does not).with then non-Racker David Cramer and Racker Todd Morey
The Planning stage usually lasts 3 weeks and consists of discussion and feedback on what the next release will focus on. After deciding on the features, we write the corresponding specs on how to make them happen. The Design Summit usually takes place during the second week of the planning stage.Blueprints are used for significant featuresImplementationThe Implementation stage is split into a number of milestone iterations. The work in progress is published in a branch, which should then be proposed for merging when ready. Code is proposed several weeks before each milestone release date so that it can be reviewed in a timely manner. QAThis is the testing phase. Testing, prioritizing bugs, and documentation are key parts of the QA phase. Only branches that fix bugs and do not introduce new features are allowed to enter the release branch. ReleaseRelease Candidate Freeze (RCF) happens two days before the actual Release Day.Codenames are cities or counties near where the corresponding OpenStack design summit took place: Austin: The first design summit took place in Austin, TX Bexar: The second design summit took place in San Antonio, Bexar county. Cactus: Cactus is a city in Texas Diablo: Diablo is a city in the bay area near Santa Clara, CA Essex: Essex is a city near Boston, MA Folsom: Folsom is a city near San Francisco, CA
OpenStack has a mirror of github.com at git.openstack.org
We progress through stages of competence. Studied by Dreyfus & Dreyfus, applied across many industries including nursing and computer software.
Applies to Archie, too. They’ll use the same information because they’re both power users. Unfortunately, most people do not meet the power user criteria (only about 2% get there).
90+9+1 = 100 = participation inequalityOpenStack-doc-core reviews and decisions to publish docs to the live production site
Next slide: blank slide
Doc core team started with me and David Cramer, it’s now a real team, driving the community forward and gaining respect.Log a doc bug in the afternoon, come in next morning to a fix.Doc commenters answering each other at six month mark.Site visitor bounce rate flipped from 2/3rd exiting to 2/3rd staying with the Essex release.TryStack and DevStack huge helpers to docChallenges:Creating true Dev guides, not specsInvestment in doc from large deployersExtensions to APIs467 config options in nova, 259 in swiftReference Architecture for Rackspace Cloud Builders (fix in progress)Training program for Rackspace Cloud Builders (recovered, not by me)100 doc bugs in backlog
Next slide: blank slide
So, how can you take these ideas and put them into practice?Everyone’s a writer, so we need to tap the power of conversation and community to add value. To be better at any job, you can use social technologies to seek info. In your job, you are helping others be better at their job by giving them info matched to what they seek. Find ways to provide value with strategic social technologies.