Author of the book, Conversation and Community: The Social Web for DocumentationI’ve had a lot of interesting collaborative authoring experiences plus I’ve been embedded on an Agile team and I’d like to share.Michael Cote challenged me to find good end user doc wiki about five years ago.worked as technical writer for Rockwell Automation, BMC Software, Advanced Solutions International, and Informatica. -served in an advisory role for LugIron in Austin, Texas, working on community analytics and social media marketing efforts. worked on an Agile software development team in two different companies, and co-authored an article about writing end-user documentation in an Agile environment for the CIDM Newsletter in 2007, Writing End-User Documentation in an Agile Development Environment. Lots of experience with open source documentation efforts and currently volunteers as a documentation maintainer for FLOSS Manuals. With FLOSS Manuals founder Adam Hyde, she organized a one-week book sprint to write documentation for the XO laptop hardware offering from One Laptop per Child and the operating system, Sugar, maintained by SugarLabs. Active member of the Society for Technical Communication, chairing of the Editorial Advisory Panel for STC's Intercom magazine and serving as a member of a special Social Media Task Force.-An early user of social media, I’ve been blogging since 2005. She writes about social media, writing, wikis, and information design at JustWriteClick.com, where she has an engaged and loyal readership.
Does documentation and support always have to suck? Why is doc hard? It’s difficult for programmers to take a user’s perspective. Traditional FOSS doc tools are powerful, but hard for non-techies to become productive.Wikis are easy to use but hard to manage, need a strong guiding hand. You’re not alone. You could burn through a huge budget trying to be everything to all users. We have to pick our priorities wisely. Let’s talk about the scene before us.
Here’s the thing. Everyone’s a writer. Content is everywhere!But. It’s hard to find. It’s incomplete.If you can’t trust it for accuracy, it’s useless.
So where do we sit? We know what community documentation usually looks like. What I believe will work for OpenStack is an approach where we curate the best community content and make official documentation out of it. Here’s the Stacker Approach.
Google Alerts, Twitter real-time searches, alerts on IRC (documentation or wiki makes Colloquy bounce up and down like Tigger)
What’s curation? It’s taking the best content and creating a usable collection that you can view like a museum-goer. Your experience should be much less frustrating than wading through everything yourself.
With Google Analytics we know what pages are most used
I believe everyone’s a writer
OpenStack Content Stackers
Content Stackers Anne Gentle email@example.comOpenStack Design Summit November 2010
Documentation is Hard,Let’s Go Programming! Source: Mattel 3
Content ‘Splosions• Wiki I find it incredibly hard to make sure that the users get the right information from the docs.• Mailing Lists On the one hand, it seems that there is already too much information as people miss things• Launchpad Answers that are already in there. On the other hand, there is always information that people• IRC are looking for, and that is not in the docs.• Code - Gaël Varoquaux, developer, Mayavi2 project• Blogs• API 4
Community Documentation• You’ve seen documentation.• You’ve participated on the social web.• You’re about to see the future of open source documentation at OpenStack. 5
Stacker ApproachWe want: We will: to deliver content in a 1. Listen and Monitor way that involves our 2. Audit and Curate community and opens 3. Involve and Engage collaboration. 6
1. Listen and Monitor• Increase signal to noise ratio• Control the fire hose flow• Take feedback from the community• Repeat 7
2. Audit and Curate• When you see something great, ask permission to use it• Ensure content licensing works for you• Recycle and reuse (single source if possible) 8
3. Involve and Engage• Come to doc sprints• License your content – Apache or Creative Commons• Talk to us, blog with us, listen with us• Read the content 9
Become a Content StackerWe want all sorts of contributors.• Join the Documentation Mailing List• Create a wiki account at wiki.openstack.org• Create a Launchpad account• Have a doc sprint at a meetup• Invite one or two people to collaborate on Etherpad• Make OpenStack documentation best-in-class 10
Any Questions?@annegentle Anne Gentlewww.facebook.com/ firstname.lastname@example.org/in/annegentle