Well, hi there. Glad you could make it. Let me introduce myself. I’m Anne Gentle, the newest addition to the hardworking OpenStack team. And I’m so eager to get started I can barely contain myself. I’ve been in lurker mode for a few weeks and now it’s time to reveal my role – I’m the OpenStack Technical Writer.
How did I get here? I first started working in open source a few years ago, and I applied my technical communication skills gladly because there is often a gap in documentation and support in open source projects. I became a big supporter of FLOSS Manuals, where we write free manuals for free software. We work in a wiki and in Booki, a new collaborative authoring platform. We also employ a book sprint technique where we focus collaborative authoring efforts into week-long sprints. I’ve helped with a few book sprints and think it’s a great technique for open documentation.
Where do I go from here? Today I want to start outlining some documentation strategy to get your feedback and tweak it. We’ll be testing doc efforts as we go and likely start with the Object Storage area.
Audit and Analysis
This phase should answer questions like, what exists already and how is it doing? I plan to do a thorough content audit right away. Seems like there are a lot of places to write things down, and I want to determine what’s out there. I’ve started reading through the Swift documentation and learning about Sphinx. We’ve all been around technology long enough to know that tools are not the complete solution, that makers and crafters help the content go from adequate to exceptional.
I’ll also study other projects (I’ve been observing several different projects for a while now). I’d like to hear your preferences here as well – how do you get information from similar projects?
An audience analysis also comes in this phase – who needs the documentation and what tasks do they accomplish with it? I expect to be prioritizing both administrator documentation and developer documentation as well as introductory information for those on their initial approach to OpenStack.
Actions:
- Build a table on the wiki showing where content exists.
- Look for reuse opportunities as well as unifying characteristics such as audience, level of difficulty, chunking, and organization of content.
- Describe the typical readers and the tasks they need to accomplish.
Creation and Collaboration
After an analysis phase, where I will avoid analysis paralysis, I want to look at content structure – what types of information should be created and where can you find them? Information typing is a huge part of what makes my life easier and more organized as a writer. Jacob Kaplan-Moss wrote a great post about writing effective documentation detailingwhat to write. I completely agree that you can write any technical documentation with tutorials, topical guides, and reference guides. I believe this approach will help us write helpful, useful documentation. I would like to build in documentation as part of the ethos of the community, part of what we value.
At first glance, the types of documentation needed may be easily divided by reader – developer documentation (which could live in the Python code with Sphinx, in the specs in Launchpad, and in Etherpad when real-time collaboration is needed) and administrator documentation (which could live on the wiki, that’s yet to be determined). We always want to consider translation and local community support, because not speaking English as a first language shouldn’t deter you from contributing to the documentation.
Actions:
- Create a Launchpad for documentation for requests and tracking purposes.
- Create a starter style guide for the OpenStack wiki.
- Talk to interested parties about contributing.
- Set up starter templates on the wiki.
- Write and edit as much as possible.
- Plan for doc sprints on specific topics to coincide with in-person events.
Goals
I think the documentation should help support users first and foremost. To me, pragmatic, viewable results come first, fancy-pants solutions are second. I think that philosophy works great at Rackspace and I’m pleased to see it’s a core value – Results first, substance over flash.
How about you? What do you think should be the goals of OpenStack technical documentation? Support? Adoption? Education? All of the above? Let us know.
What can you do to help with doc?
Please, introduce me to people who want good documentation and recognize good doc. Introduce yourself or name others. Send me examples of sites that do it well. Write things down as you go, even if they are rough notes. Help us shape a doc strategy so it fits our community.
You can read more about me on my blog at JustWriteClick.com, on Twitter @annegentle, and get in touch any number of ways – comment on my posts, talk to me on Twitter, email me at anne at openstack dot org.
I’ll be asking lots of questions as I get started, but these are my initial thoughts. Ready to start stacking!