The OpenStack Blog

Category: Documentation

OpenStack Documentation Wrap Up for 2013

It’s that time of the new year to reflect and look for ways to keep improving the OpenStack docs. Here’s a list of major events from 2013 in OpenStack doc-land. Let’s look at the year in review.

  • Operator Guide book sprint was in February 2013 and I still remember it fondly. The before post and the after post tell the tale, as does this video.
  • Diane Fleming added a sidebar for navigating the every growing API reference site at http://api.openstack.org/api-ref.html. I’d like to see more improvements to the design for that page with more responsiveness for different devices.
  • We have improved the DocImpact commit message flag, where developers can add DocImpact to a commit message, and some automation happens in the background to automatically log a doc bug, setting it to New until the patch actually merges, eliminating a lot of manual steps. Props to Tom Fifield and Steven Deaton for this accomplishment in 2013.
  • We also were able to simultaneously release the docs with the code for the Havana release in the fall for the first time. A large part of this accomplishment is thanks to automation of the Configuration Reference, where the auto doc tool scrapes the docstrings and collects them into meaningful tables per feature per project.
  • This year included a complete reorganization of the docs.openstack.org site landing page. We also added new titles to try to accommodate new audiences. We have a new user guide and admin user guide, which walk through both the Dashboard and command-line interface procedures to accomplish common tasks like launching an instance. As I mentioned above, we’re also maintaining a new Configuration Reference which lists all possible configuration options across multiple OpenStack projects.
  • This year after the Summit in Portland, I worked with Lew Tucker’s finely tuned organization at Cisco to hire a contract writer dedicated to the upstream vanilla OpenStack install guide. There were still hiccups and delays despite having a dedicated resource, but the resulting install guide has been well-received.
  • We held a mid-release OpenStack Docs Boot Camp in sunny California at the Mirantis office. We learned a lot from each other and got to know contributors we hadn’t met in person.
  • In July 2013, the OpenStack security team put together a fantastic OpenStack Security Guide with a book sprint in an undisclosed location in Maryland. At least I think that’s where it was.They’re security conscious.
  • The High Availability Guide got some refreshing as well, thanks to Emilien Macchi and Enovance test labs.
  • We have Japanese fonts now supported in our tool chain, with Japanese translations now available on docs.openstack.org/ja/. Much appreciation to the translation team, especially the Japanese team lead Masanori Itoh, I18N team lead Daisy Guo, and David Cramer for the doc tooling for the font support.
  • Also in 2013 we have been incubating the open source training manuals team within the OpenStack Documentation program. They’ve produced an Associate Training Guide, with outlines and schedules for an Operator Training Guide, a Developer Training Guide, and an Architect Training Guide. All guides and outlines are available at http://docs.openstack.org/training-guides/content/.
  • At the Summit in Hong Kong we announced that the OpenStack Operations Guide became an O’Reilly edition and we are working on the edits coming back from our developmental editor.
  • Most recently we had a Doc Bug Day on 12/20/13 squashing over 80 bugs, following the sun from Australia to the US west coast and then some.

This past year OpenStack Documentation became an official program with me, Anne Gentle, elected as the Program Technical Lead. I hope to continue to serve and promote the Documentation efforts as we go into the new year. Yes, I do read the feedback from the user survey and I know we have work ahead of us. But for the docs to be second-most complained about instead of first-most was a moment to be celebrated in 2013. Thanks to the many contributors who make these incremental improvements happen.

OpenStack Operations Guide now an O’Reilly Early Edition

You remember the crazy feat we’ve pulled off twice now, writing a book in five days? Well, the Operations Guide is now available from O’Reilly as an Early Release. Get a free downloadable copy at docs.openstack.org/ops/.

9781491947685_ER

What does this mean, you ask? You can download a copy now that shows you the state it’s in today, and then stay tuned for the next few months while the authors and editors update it, making it more polished, more clear, and more accurate for the Havana release. Plus, glory be, it’ll have an index. We should be able to release a few fully edited chapters at a time as we work, and our goal is to continually publish our HTML and PDF version by sharing the content across Gerrit and Github.

O’Reilly’s collaborative authoring system is called Atlas, and it is backed by Github. Our authoring system is backed by Gerrit with our review process in place managed by the docs core team. We’re working through the workflow that will enable synchronization between Git and Gerrit so that you too can be a part of this book. Get your writing hats on and typing fingers nimble.

On Twitter last night in Hong Kong, I tweeted out the link to the book and asked the question, what is the animal on the cover? My next tweet then hinted that it’s a distant relative of the animal on the cover of Deploying OpenStack. Do you know what it is?

It’s an agouti! They can jump straight up six feet in the air! With those feet I believe it. Agouti’s are related to guinea pigs. Everett Toews and I just call it the “big butt rat.” Heh. I hope you’ll get behind our guinea pig experiment with book making while we all work hard to bring you best practices and hard-earned lessons learned about operating OpenStack clouds.

How to Use Ask OpenStack

We’re continuously building together “The best place on the Internet to find answers to common OpenStack problems”: our Question&Answers site Ask OpenStack is such place and needs everybody’s help. Ask OpenStack is a collaborative effort, think of it like a wiki where pages are made only of questions and answers. Anybody with more than 100 karma points can fix a question or an answer and anybody can gain karma points by getting votes on answers and/or questions.

We have collected some suggestions to use for those that ask questions and those that answer in our wiki. The sum of it is:

If you’ve used Ask OpenStack to ask questions or to give answers, please let us know what you think and how you would see it improved in the comments below.

vote-up

Remember to vote good questions and answers on Ask OpenStack!

To the first OpenStack Documentation BootCamp

The OpenStack Docs Bootcamp offers a deep dive into the technical tools, workflows, and processes we use to create docs.openstack.org and api.openstack.org. Our goal is to give enough information that will create sustaining new core members of OpenStack Documentation.

Inspired by the first successful Infrastructure BootCamp, the OpenStack Documentation BootCamp is an in-person, intensive sprint for people who are looking to get involved deeply with OpenStack Documentation and need a leg up into the process.  Participants to the BootCamp will be all together in the same room, with their laptops and get them setup with the tool chain.

The two days event is structured so that the first day is an introduction to tools and processes, mainly aimed new contributors; day two is the deep dive into the content of all docs and manuals, with existing and new contributors on the same level.  The Docs BootCamp will be on Sept. 9-10 in Mountain View, CA by Mirantis offices.

You can register to attend through this form. More details on the OpenStack wiki.

OpenStack Security Guide now available!

The legendary book sprint method has come through again! This past week in a bunker, I mean, secure location near Annapolis, a team of security experts got together to write the OpenStack Security Guide. I’m pleased as can be to have the privilege of sharing the epub with you here and now, the evening of the fifth day!

Download the epub file and start reading. One of the goals for this book is to bring together interested members to capture their collective knowledge and give it back to the OpenStack community.

This cover gives you a glimpse of the amazing feat this team pulled off. We’ll have HTML and PDF in the next couple of weeks to fulfill your multi-output consumption wants and needs. For now, fire up your ereader, and start reading! The team wants your input.

Lessons, Learning, and Long Views for Internship Programs

In January 2013 the OpenStack project welcomed aboard three interns and excitedly assigned them to work on fairly complex projects in our first attempt at an organized project-level internship program. The OpenStack Foundation participated as one of the organizations with the GNOME Outreach Program for Women and learned quite a few lessons during the six months internship period.

By February, two of the interns had learned the tough lesson of what happens when coordinated work efforts move at a fast pace. For example, Laura Alves, an API documentation intern had a patch with a manually created WADL for the Networking project nearly completed. She started requesting reviews from the core developers. We soon discovered that the devs were working on an automated method for creating the WADL. It certainly took some quick communication and coordination to make sure her work wasn’t wasted. Her efforts certainly weren’t wasted but it also hasn’t landed quite yet either. Lesson learned: internship projects are difficult to scope and it’s nearly impossible to set aside tasks in a reserve area just for interns.

Still more lessons learned were that the timing of code freeze dates landing prior to the internship’s completion made for a steep on ramp for new interns with early deadlines. We also found that interns can contribute so much right away with their fresh perspective — and they created such valuable blog entries for newcomers, like Logging and debugging in OpenStack by Victoria Martínez de la Cruz,  so they’ll be helping more newcomers for months.  We pulled all our lessons learned together for a “What Everyone Should Know About OpenStack Internships” panel session at the Summit in Portland.

One of the takeaways from the Summit was to learn more about mentoring from Katy Dickinson, and the blog at MentorCloud where she is Vice President has been very valuable to learn from as we continue to shape our plans for interns wanting to learn and contribute to OpenStack. Katy attended our brainstorming session at the Summit and gave us very useful suggestions. We surveyed outgoing interns and are working on a plan to coordinate early and often to identify and promote natural mentors in the OpenStack community.

The more you look for internships and mentors in OpenStack, the more you’ll find. Cisco has interns working on OpenStack projects each summer. One OpenStack intern, Emilien Macchi, at StackOps went on to do a graduate part-time internship at eNovance. Rackspace has interns working on multiple OpenStack projects.

The Foundation is continuing the involvement in the Outreach Program for Women also in the northern hemisphere’s summer edition: Terri Yu started working on the Ceilometer project with Juilan Danjou at the end of May: be sure to welcome her! Look for more opportunities to connect the dots with interns and mentors in the coming months. If you have funds for travel so interns and mentors can meet each other in person, let Stefano Maffuli know. If you have a great intern story to tell, please let us all know.

Introducing the OpenStack Operations Guide

Planning to run, or design an OpenStack Cloud?  There’s a new book you should take a look at – the OpenStack Operations Guide.  Get your free download now at http://docs.openstack.org/ops/!
OpenStack Operations Guide
You may have already seen the blog post, We Did It: Zero to Book in Five Days, from Anne Gentle, the OpenStack documentation coordinator who came up with the idea to write the book sprint-style and gathered the team – including myself.
Screen Shot 2013-03-13 at 10.29.48 AM
Our overarching guidance (and why you should read this book) when writing was to share our experiences. The authors have all lost sleep and worked through holidays to nurse OpenStack clouds into a production-ready state. To that end, the book covers two main sections: Architecture and Operations.The aim of the Architecture section is to, once you’ve understood enough about OpenStack to realise that you are actually going to build a cloud using it as a basis, step you through many of the common and non-so-common concerns to deliberate while in design. Some of it might be principles you consider standard already, but others look to specifically address the hard questions specific to this platform. Questions like “How do you scale your OpenStack cloud?”, “How many servers should you buy for control infrastructure?”, “Should your storage be external or in the compute node?” are covered in an opinionated manner, with realistic perspective on what works.This book does not include installation instructions. This is already covered in the installations guides at http://docs.openstack.org/install/, so the book segues into Operations assuming that you now have a working cloud – though a pre-install skim is a good idea too.In the Operations section, we really tried to consider running OpenStack from the perspective of a time-poor systems administrator. It starts with a to-the-point tour of your cloud via the commandline as a way of familiarising yourself with what will be your working environment. Following this is a compendium detailing ways in which you’ll be working with the cloud. “User Facing Operations” attempts to give you enough of a perspective on what users are trying to do at the IaaS level that you can can help them, while “Maintenance, Failures and Debugging” works on the dual principle of fixing broken services, or preventing them from breaking in the first place.Two important chapters end the section – “Customise” and “Upstream OpenStack”. Openstack is as much of a community as it is a software project, and the latter gives some insights on how to interact with the community – including how to get help when you’ve tried everything else. The former, probably the most advanced chapter in the book, assists in taking advantage of the framework to extend it without touching the core code. Hopefully you’ll use the two in conjunction and share your work with the community!For excellent bed time reading – perhaps to help understand that others are in the same boat, and reduce those stress levels – there’s an appendix called “Tales from the Cryp^H^H^H^H Cloud”. Here, a few of us share our OpenStack operations stories to help you understand the processes we go through when the stakes are high.

It’s been a privilege working on this book for you – learning as much as contributing – and I hope you find it useful.

History behind the book:

The creation of this book happened in just five days, but the story that goes with it is a little longer. More or less since people started using OpenStack for their production clouds (let’s call that Cactus timeframe – those before that were fairly ‘brave’) there’s been a request for information on the best practices for designing and running our favourite cloud software. As it were, the small number of people working on documentation were struggling just to keep track of the hundreds of configuration options that make this framework so flexible. Then, in May last year, Anne Gentle created a seemingly innocent blueprint “Create and OpenStack Operators Manual”, and started gathering a team – people who’d spent months sacrificing their sleep to tune their OpenStack deployments, and able to share their knowledge.

Originally, the proposal for a book sprint was submitted to Google Summer of Code’s documentation track – it didn’t make it in. The OpenStack foundation came to the rescue, providing the funding needed to get the writers to the one place and keep them fed. Thanks to the Book Sprint methodology, from February 25th to March 1st, 2013, the authors worked out of Austin, Texas producing more than 10,000 words  a day, allowing a launch of the book the following week.

We Did It: Zero to Book in Five Days

OpenStack Operations Guide Call me crazy, call me maybe, but we did it! We have a 50,000 word book, 230 pages long, now available for download in your favorite ebook format, or purchase a printed copy if you like the no-batteries-required version. Go to http://docs.openstack.org/ops/ to get a copy and watch a video we made on day four.

We started the week off with a cookout at Everett Toews’s house. I transposed the house numbers and walked up to the wrong house, rang the bell and everything! A nice Texan lady told us we looked like we were going to have fun but the party wasn’t at her house. Woops! We found the right house on the same street and had a great time. The evening was complete with peach cobbler as we nervously awaited our fate: Could we complete a book in a week?

On Monday we assembled to find out. In a room with an entire wall of white board, our facilitator Adam Hyde unwrapped packs and packs of sticky notes with fresh markers. He introduced the book sprint process and said that he has done about 55 of these. He also said we may not get the book we thought we would going in, but by the end we will get the book we need. Sure enough, we collectively wrote about 10,000 words a day, bringing in all the content we could, revising, reshaping, rewriting, until it all hung together as a real book.

Our hope is that it is the book we all need, that it fills a gap for an under-served audience, the operators of clouds. We want your input, so start reading!

 

 

Bring on the Crazy: Zero to Book in Five Days

Well, since my team mate Everett has outed me as crazy (yes, it’s true), I think I’ve got some ‘splaining to do! It’s true, we’re crazy, but we’ve got to write that operator’s guide — for operators by operators. And if you know ops folks like I do, you realize quickly that these guys have hardly any time to write down their notes! We’re going to pluck them from their day jobs, fuel them with coffee, BBQ, and TexMex, and get to writing.

I’ve run doc sprints for OpenStack at various times on different scales, but this one is highly focused. So highly focused in fact that I’ve turned down people who wanted to attend but hadn’t run clouds day-to-day. Sorry guys! Super hyper focus, blinders on.

I had originally put the proposal together for the Google Summer of Code Doc Summit, which I attended in 2011, but out of 30+ applying organizations, we weren’t selected. Undaunted, I revised the proposal for the OpenStack Foundation to consider, and they are funding it!
1-IMG_3304
We’re gathering in the Willie Nelson room at the Austin Rackspace office next week, and we’re going to try a tool called BookType, hosted by Source Fabric. It’s the same tool I’ve worked with for book sprints with FLOSS Manuals, and it’s made specifically for sprinting. We’re using a pre-installed instance of it at http://openstack.booktype.pro. If you look at it today, it’s empty except for a Test book sandbox. By next week it’ll be bursting with content! The outline we’re working with to start is at https://etherpad.openstack.org/EssexOperationsGuide. Thanks to everyone who has reviewed it and commented so far.

You all are welcome to watch our progress next week at at http://openstack.booktype.pro and offer editing and reviewing as we go. Please realize it’s a pressure cooker of a week, and a real challenge. I’m saying, be helpful and encouraging so we can be productive and accurate. Once we’re done, ship it! We’ll have copies of the book available (likely for a donation initially to cover costs) by the end of next week.

If you want to hear all the gory details, we have a few opportunities. Next week, if you’re in Austin, come see us at the Austin OpenStack Meetup on Wednesday night. Then, at the Summit, we want to bare our souls at a panel titled, On Writing the OpenStack Operations Manual in 5 Days. Come see if we are crazy, or driven there this week.

Vietnam OpenStack Community 2nd Meeting

Following the success of the first Vietnam OpenStack Community (VietOpenStack) meetup, the second meeting has been held at Marcel Dassault amphitheater, Francophone Institute for Informatics (IFI-VNU) on 4th January, 2013. There were approx. 50 people attending this event. We warmly welcomed:

  • Representatives from IT Business Management level: Mr. Nguyen Huc Quoc – Director of e-government center, Department of Information and Technology, Ministry of Information and Technology, Mr. Nguyen Hong Quang – Chairman of Vietnam Free and Open Source Software Association (VFOSSA), Mr. Nguyen The Trung – Managing Director of DTT Technology Group (DTT), Mr. Do Hoang Khanh – Former CTO of Citibank Global, a senior expert on IT of DTT, Mr. Tran Luong Son – Director of Vietsoftware, Mr. Le Phuoc Thanh – Managing Director of VidaGis…
  • Representatives from ICT companies: Vietsoftware, Netnam, iWay, VidaGis, Viami Software, DTT …
  • Members of VietOpenStack start-up team: Translation sub-team, Technical sub-team…
  • Teachers and students from technology university: Francophone Institute for Informatics (VNU-IFI), Hanoi University of Industry (HaIU), Hanoi University of Science and Technology (HUST)…

The 2nd VietOpenStack meetup took place in a friendly, enthusiastic and full-of-energy atmosphere and the “Open” spirit was clearly shown in every presentation and discussion of the participants. Starting the show, Mr. Nguyen The Trung, Managing Director of DTT introduced the agenda of VietOpenStack Meetup 2 and special guests.

Mr. Nguyen The Trung, Managing Director of DTT, introduced VietOpenStack Meetup 2 agenda.

Main contents of 2nd Meeting include:

  1. OpenStack Demo
  2. Translation of OpenStack Documents
  3. OpenStack experience sharing of an IT expert
  4. Q&A and future plan

 1.  OpenStack Demo

Mr. Nguyen Thanh Hai from Netnam introduced his company as one of the Internet Service Provider (ISP) company providing internet and network services. He then conducted a demonstration on OpenStack installing model.

Mr. Nguyen Thanh Hai from Netnam demonstrated OpenStack installing model

2. Discussion on OpenStack Translation

Ms. Le Phuong Nga, member of OpenStack Translation team from DTT, started her presentation by introducing all members of the OpenStack translation and reviewing teams. She then briefed on recent team activities and translation progress in which Vietnam has completed 9% of the translation work. She also raised some translated related issues while her team doing the translation to the community, such as difficulty in getting the translated work reviewed by the reviewing team.

Ms. Lê Phương Nga, member of OpenStack Translation team from DTT, with her presentation on OpenStack translation.

3. OpenStack experience from a senior IT expert

Mr. Do Hoang Khanh, former CTO of CitiBank Global and a 30 year experience IT consultant of DTT Technology Group, is a person who is passionate about open source movement. He also attended the OpenStack Summit last October in San Diego. He shared with the participants his personal experiences and knowledge on OpenStack. What a touching presentation he has given for this meetup event!

Mr. Do Hoang Khanh, former CTO of CitiBank Global and a senior IT consultant of DTT Technology Group, sharing his experience on OpenStack.

4. Q&A and future plan

Although there were some questions and answers during the whole meeting, group discussion really started when beers and snacks, sponsored by DTT, were served to the attendants. People drank and shared more openly on OpenStack and opportunities it could bring to ICT companies in Vietnam. Everyone was eager for the next meetup, which is tentatively to be held in Ho Chi Minh city. And yes, discussion for Meeting 3 is on the mailing list now. It will be announced very soon :-)

We especially thank Mr. Nguyen Hong Quang, Chairman of VFOSSA and his team for being so supportive in organizing the meetup place. Great hospitalities has made to the success of VietOpenStack Meeting 2.

It’s time for meetup dinner

5. VietOpenStack contact details:

 

Back to top