OpenStack Doc Overview for Boot Camp
Download as PPTX, PDF2 likes7,595 views
This document provides an overview and schedule for the OpenStack Documentation Boot Camp held in September 2013. The schedule outlines presentations on various documentation topics that will be given each day. It encourages participants to ask questions, try hands-on labs, and contribute discussion topics. It also thanks the event hosts. The goals are to increase OpenStack adoption, provide support, be strategic and collaborative, provide truthful information, and achieve business objectives.
OpenStack Doc Overview for Boot Camp
- 1. OpenStack Documentation Projects and Process OpenStack Docs Boot Camp Anne Gentle September 2013
- 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!
- 4. ® I Believe in Community Flickr: seier+seier
- 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
- 12. ® OpenStack Projects - Integrated •Metering – Ceilometer •Orchestration – Heat •Libraries – Oslo
- 13. ® OpenStack Projects – Incubated or Applying Incubating: •Databases – Trove •Bare metal – Ironic Applying: •Hadoop (NoSQL) – Savannah •Queuing – Marconi
- 14. ® OpenStack Release Process • Planning – Design Summits – Blueprints • Implementation • QA • Release – Release milestones – Release Candidate Freeze – Feature Freeze Exception – Release naming – Release numbering
- 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
- 16. ® OpenStack Documentation Processes – Launchpad •Bug logging •Bug triaging •Bug assigning
- 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
- 19. ® OpenStack Documentation Processes – Book Sprints, a book in a week
- 20. ® Where Documentation Processes Diverge from Development Processes •Does not track milestone releases yet •Translation automation being set up
- 21. ® OpenStack Documentation •Who are our audiences? •What are their tasks and jobs? •How can we focus doc efforts?
- 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
- 27. ® Analytics: Sept 2012 Contributors Doh. Release date. Hey! Release date!
- 28. ® Analytics: Sept. 2013 contributors We are here.
- 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.
- 31. ®
- 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.
Editor's Notes
- #2: I am a content stacker at Rackspace, here’s where I think we’re going
- #3: 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.
- #8: 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.
- #11: There are now seven OpenStackprojects, six of which have APIs (the Dashboard does not).with then non-Racker David Cramer and Racker Todd Morey
- #15: 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
- #18: OpenStack has a mirror of github.com at git.openstack.org
- #24: We progress through stages of competence. Studied by Dreyfus & Dreyfus, applied across many industries including nursing and computer software.
- #26: 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).
- #27: 90+9+1 = 100 = participation inequalityOpenStack-doc-core reviews and decisions to publish docs to the live production site
- #28: Next slide: blank slide
- #30: 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
- #31: Next slide: blank slide
- #32: 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.