Tag: content


Doc Plans for Upcoming OpenStack Releases

November 30th, 2010 — 12:55pm

I’m supposed to be strategic about documentation and well, I have to say I feel a bit behind in creating specs for documentation for the upcoming OpenStack releases. Much spec planning went on at the Summit, but I was so focused on the Doc Sprint that I didn’t set any concrete doc plans for Bexar and Cactus releases. I’d like to amend that and get input from everyone in the community and beyond. Here are some ideas that go into a single blueprint for documentation. I’d love to get feedback on these plans and specifications, which we can edit on the wiki.

1. Docs site – OpenStack needs a central docs.openstack.org site that curates the content from various other sources and gives a good user experience upon landing on it. My goal is to implement this in time for Bexar (February).

2. Official docs – OpenStack needs a way to indicate that a page or site as “official OpenStack documentation” meaning that it is as accurate as we can get it and the procedures have been tested. Again I’d mark this for Bexar.

3. Versioning documentation – We are taking small steps towards a frozen release page/site. For example, you should be able to go to http://swift.openstack.org/1.0/ and get a frozen-in-time site with the developer documentation from the 1.0 release. We can get this done in time for Bexar.

4. Man pages – We need man pages created for nova-manage, nova-compute, and nova-networking. The nova-manage man page is now in the builds but needs editing. It is sourced in doc/source/man from RST files and gets built with the Sphinx docs. This could be done for Bexar.

5. Tutorials – Now that we have virtual boxes and stack on a stick in progress, we need tutorials that are meaningful and simple enough to step through while still giving an impressive demonstration of the power of OpenStack clouds. Here are some ideas for tutorials:

  1. Create a LAMP stack for a web application like WordPress – demonstrate connectivity between virtual machines, describe how to scale as your blog gets super popular (hey, we can dream, right?)
  2. Build your own CDN to serve video content
  3. Academic calculations where you spin up 10 machines for a Mathematica project only for a day or so
  4. Create a news reader application using AMPQ/RabbitMQ

I think we could have one solid, tested tutorial done in time for Bexar with the remaining set for the Cactus release. Any thoughts on how to prioritize these tutorials? Which would be in highest demand?

6. Glance docs – With the Glance implementation still ongoing for Bexar, we need to plan for install and integration docs with the Bexar release.

Let me know your priorities for upcoming releases and we’ll update the specs for the encapsulating blueprint for docs work. The Docs site is the biggest item needing design and architecture, so I’d welcome input and ideas with a heavy weighting towards “Docs site!”

1 comment » | Development, Documentation

Content Stacks

October 28th, 2010 — 4:32pm

Yep, content does stack, and I wanted to describe some of the content stacks we have going now. It’s like pimp my ride, where’s the noun and where’s the verb?

Stacking Up

The OpenStack community has embraced technical content and the surrounding community is hungry for more. We’ve had great contributions from community members. A couple of highlights to me are the enthusiasm and friendly lines of questioning by David Pravec (alekibango on IRC), plus his outlines in Etherpad have been excellent starters for Nova manuals. He also feels passionately that we are creating manuals, not guides, providing exact information rather than just guidance. We also had Stephen Milton (grizzletooth on IRC) step up and take the Swift All In One page and test it on multiple servers, providing a brand new multi-server installation and deployment page that we’re still drafting. A student in Florida, Eric Dorman (Orman on IRC), who is studying security in the clouds, is writing security documentation for OpenStack. This turnout encourages me so much, thanks all.

We’ve got a Documentation page that stores the collection of pages we’ve started and outlines the plans for what pages need to be written. I really liked this blog post, Two months writing docs for Open Atrium and Managing News – lessons learned! and borrowed the outline ideas from there. It confirmed my thinking that there are a lot of expectations for technical documentation for completeness, and this outline, once it’s filled in, would bring a sense of “completeness” to the OpenStack documentation.

The nova.openstack.org and swift.openstack.org sites should be freshly outfitted with Google Analytics by the end of this week. We should have Google Analytics integrated in the wiki soon as well. This integration will give us ideas about which pages are often viewed, what searches bring people to the site, and the paths they take once they’re on the wiki for example.

One work area that has surprised me a bit is the use of Etherpad to write drafts and collaborate with a small group before putting the information on the wiki or in RST. We’ve coded Etherpad pages in RST so it’s a simple copy/paste to get the RST in the Sphinx build. I understand the feeling that writing drafts on the wiki feels like working on the document on the operating table with its guts hanging out. So having a more private collaborative area like Etherpad seems to bridge the gap between wiki page drafts and early, early drafts.

Doc Sprint

I’m shaping the agenda for the upcoming Doc Sprint the last two days of the OpenStack Design Summit. All times are Central Standard (GMT -6). Here’s how it’s looking:

Thursday Nov. 11

9:00-10:00 Attend Install Fest and install environment, update install
instructions
10:00-10:30 Training in either wiki or RST as needed, plan writing
assignments
11:00-12:00 Write
12:00-1:30 Lunch
1:30-2:00 Community Manager Stephen Spector to talk about documentation
recognition
2:00-4:00 Write
4:00 End of day check-in (IRC and/or con call)
6:00 Don’t forget the party is Thursday night, all doc contributors are
welcome! Buses will depart the Weston Centre lobby at 6:00.

Friday Nov. 12

9:00-12:00 Write
12:00 Mid-day check-in (IRC and/or con call)
12:00-1:30 Lunch
1:30-4:00 Write

The check-in at the end of the day enables us to connect with remote contributors, switch writing assignments, ask questions and so on. If you’re planning to participate remotely, please let me know so I can accommodate your needs. We’ll be on the #openstack IRC channel all day, and we can use a conference call or Skype if you’d like to listen in on Spector’s talk.

Official Content Stack

One of the goals for this quarter is to find a way to distinguish “official” documentation from “ongoing, in testing” documentation. Whether it’s a badge on a page or a whole new URL such as docs.openstack.org, I’d love your thoughts on how to indicate when a doc is tested, vetted, and official. I have ideas and examples but the community opinion matters and has weight in the decision, so please offer your ideas. You can email me at anne at openstack dot org, find me on IRC as annegentle, or find me on Twitter @annegentle.

1 comment » | community, Documentation

Back to top