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.
Leave a Reply