OpenStack Doc Sprints
A doc sprint is an intense collaboration session with the express purpose of producing technical documentation to meet the needs of certain audiences. Not quite a writing retreat due to the intensity and focus of the session, it is an opportunity to work only on documentation be it online or intended for print production. For OpenStack, we plan to hold doc sprints at each Design Summit with particular goals in mind for each session, held about every six months.
FLOSS Manuals, an online community dedicated to free documentation for free software, has written a book sprint guide, describing a method to carry out collaborative authoring in a short time with the express goal of having a publishable book at the end. The Book Sprint concept was devised by Tomas Krag. Tomas conceived of book production as a collaborative activity involving substantial donations of volunteer time.
Tomas pioneered the development of the Book Sprint as a 3-4 month production cycle, while Adam Hyde, founder of FLOSS Manuals, was keen to continue with the idea of an "extreme book sprint," which compressed the authoring and production of a print-ready book into a week-long process.
Doc Sprint at OpenStack Design Summit, November 11 & 12 2010
After the business and technical sessions are complete, the doc sprint will be held Thursday all day and Friday morning, mostly in the same collaboration room but small groups or individuals may also write independently. Remote participation is allowed since we will have two check-in periods to help people with assignments or get information.
If you want to take an assignment, put your name and/or IRC handle next to a bulleted item. For more details about each assignment, see information below the table.
Our To-do list can be found here: http://etherpad.openstack.org/DocSprint
- Nova - A class/interaction diagram is started but needs to be brought into the wiki if possible. graffle file (and an exported png) http://term.ie/data/nova.graffle and http://term.ie/data/nova.png
- Nova - Doc strings are in the code. We have docbook source for the Cloud Servers API but it's going through enough changes that we'll delay work on it for now.
- Swift - We have docbook source for the Cloud Files API, which will get an OpenStack treatment by placing in our system with output that .
Installation Pages - Do these need editing or updates? (I think they're close to done.) Do we need to create .RST equivalents of the Swift All in One and Multi Server Install for Nova?
- NovaInstall/MultipleServer - Ensure that these carry through all the details from the Etherpad at http://etherpad.openstack.org/NovaMultinodeInstall.
Nova Manuals These are drafts, ready for writing. They have some guidance written as notes in the text.
- [[[NovaAdminManual||OpenStack] Compute Administration Manual ]] - How to configure and maintain and monitor Nova.
- [[[NovaDeploymentManual|| OpenStack] Compute Deployment Manual ]] - Should also link to the installation pages but go beyond installation into hardware selection and customizations.
- OpenStack Compute Security Considerations - http://etherpad.openstack.org/NovaSecurityNotes is a working draft, move it over to the wiki as needed.
Glance Manuals Glance is the VM image repository for OpenStack. I'd like to get some documentation plans going for Glance, starting with how to install it and how to implement it with Nova. Eventually we'd also document how to use Swift as an image store. Please draft installation and integration notes here: http://etherpad.openstack.org/GlanceDocs.
Configuration Pages for Nova
- Flag Files for Nova - need the remaining services to be documented.
- Networking - Nova networking needs documentation to explain the configuration, you can use https://lists.launchpad.net/nova/msg00299.html for starters. An architecture diagram to replace the ASCII art in that list post would be useful.
Networking Pages for Nova After speaking to a couple of Nova developers today, I found they are actively updating the nova.openstack.org docs and my only suggestion was to add a Deployment Guide with a Networking section.
Docbook output The Rackspace API guides that are a starting point for OpenStack API guides are currently in docbook. Hopefully we can spend some time working on nice output, perhaps using the new WebHelp output.
Feel free to add assignments to this list.
Thursday Nov. 11 - Discovery Room
9:00-10:00 Orientation Install Fest will happen Friday, but we will update install instructions Training in either wiki or RST as needed, plan writing assignments
1:30-2:00 Community Manager Stephen Spector to talk about documentation recognition
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
12:00 Mid-day check-in (IRC and/or con call)