Anne Gentle has been involved in creating documentation in wikis for awhile now. In the 2009 first edition of Conversation and Community: The Social Web for Documentation, she offered her experiments as a practical guide to persuading management to bring users into your documentation projects. In the expanded second edition, Gentle adds the experiences of other technical communicators to make the case for taking advantage of passionate users to create the best possible docs for your software.
Collaboration and teamwork is nothing new, either for software developers or technical communicators. One benefit that the free software movement has given all of us is the idea thaollaboration in his 1996 essay, “The Cathedral and the Bazaar.” Perhaps the best known of these rules was borrowed from Linus Torvalds, the founder of the Linux operating system. Raymond wrote: “Given a large enough beta-tester and co-developer base, almost every problem will be characterized quickly and the fix obvious to someone. Or, less formally, ‘Given enough eyeballs, all bugs are shallow.’”
Gentle argues that the same principle can be applied to product documentation. “Documentation as conversation means getting closer to user and helping them perform well,” she writes. “Now, writers can take the idea of user-centered design a step further by starting conversations with users and enabling user assistance in interactions.”
The book covers how to get started in identifying the best ways to begin the conversation with users, whether it’s a wiki, blog, web-based forum, or even Twitter. She also gives guidelines for selecting platforms.
Better Product Documentation with Book Sprints, Content Strategy and Analytics
One of my favorite sections is the discussion of “book sprints,” pioneered by the FLOSS Manuals project. In a book sprint, normally widely-scattered developers, writers and users come together for a few days to create or update a set of docs for an open source project. Gentle explains how to plan and carry out a successful book sprint, factoring in all the costs and logistics of the project.
The second edition offers new chapters focusing on content strategy, using web analytics to discover more about your users and what they seek help with, and the process of documenting open source software. You’ll learn about content and community audits, how to build a community of users, and how to participate in open source documentation projects.
Besides Gentle’s own experience building conversation and community with a variety of organization, this edition is informed with interviews and case studies from tech writers at companies like AutoDesk, IBM, Red Hat and Embarcadero.
The book does have some organizational issues. At times, I was not sure whether I was reading about early experiments with social documentation, making a business case, or already into implementing a social strategy. Nonetheless, Gentle consistently addresses the business value of documentation generally, and social documentation as pointing to the future of software documentation.
Conversation and Community is an excellent introduction to the value of bringing in users to your user assistance toolkit, and will help you overcome management resistance to implementing a social strategy. You can also learn how to get involved in open source documentation projects, especially if you’re new to our profession.
