Andy Oram
August 17, 2009
A few years ago this book could not have been written, because the phenomena it describes were just poking their heads out of the sea, and no one could predict what form their evolution would take. A few years from now this book will be unnecessary, because we’ll all be participating so fully in the phenomena that newcomers will take to them like ducks to water. You are fortunate to have this book at this moment, for you can lead the next generation of information providers into the era of expert/amateur interaction.
Anne Gentle purports in this book to give you the tools and insights to create growth-oriented educational experiences for your clients in this age of collaborative learning. To bring home the goods, Anne has combined hard-won insights from every angle: academic research, reports from the field by other cutting-edge practitioners, years of experience in corporate technical writing departments, and personal practice as a contributor and organizer in some of the most sophisticated of open-source, community-oriented authoring sites.
I’ve exchanged mail with Anne and worked with her on FLOSS Manuals, an experiment in free documentation that takes center stage in many of the examples in this book. Having toured some of the same ground as Anne, having enjoyed some of the same views from the commanding heights, and having been caught in some of the same downpours, I can attest that she has the landscape right.
FLOSS Manuals is just one of the many projects on the Internet that show the power of people working together to educate the public with documents open to all for editing and distribution. Among the lessons these projects offer is the tremendous energy that arises from public engagement. But they also show that this energy is more potent when managed well.
Because client education, as a key element of client satisfaction, is the concern of anyone working on a project with outside stakeholders, this book should claim a wide audience. The main targets of the book are technical writers at companies experimenting with social media (also known as Web 2.0). But among the barriers to collaboration sliced away by Anne’s scalpel is the distinction between official technical documentation, marketing-oriented white papers, release notes, customer service forums, and even customer comments in the field. If you work in technical development, marketing, customer support, or that most intriguing new job description—community manager—this book has news for you.
Every source of information with which we’re familiar—journalism, education, government, and certainly technical documentation—is abandoning the oracular view of information. In simpler days, those of us in documentation and publishing found experts and simply proclaimed their insights to the masses. Now we realize that many of those insights originated among the masses in the first place. Furthermore, writers and publishers find that their work doesn’t get read unless the expert conducts a dialog with the audience.
We may know what they need to know, but only they can tell us what they need to know.
I’m hoping that the context for the previous, artfully crafted sentence ensured it had the proper impact, but in case your reader response didn’t work as I had hoped, let me spell it out. Experts possess knowledge that other people wish to mine, and often will pay for. But the experts often can’t anticipate the questions that non-experts will have. The experts are shocked to discover the areas where non-experts experience difficulties. Once they understand their audience better, most experts radically alter the topics they discuss and how they present them. Thus the importance of conversation and collaboration between experts and non-experts.
Many of us worry about our future in an environment of blogs, wikis, and stakeholder forums, where anyone who knows anything can share it. The question “How can I earn a living?” must be approached in Through the Looking Glass fashion, by walking away. Join the online conversation. If there’s a place for you as a professional, you’ll find it there.
Occasionally I talk to someone who believes that self-help and self-organization are taking the whole pie, and that the best sugarplums will pop up on their own. If that were true, the world wouldn’t need professional editors and information architects, and it wouldn’t need Anne’s book. But these misguided futurists have it profoundly wrong. Experts and non-experts need to work together.
I finally got provoked when one programmer boasted to me that he never read any documentation. He looked at the source code of the software he was planning to use as a start. He would write code till he hit a barrier, then ask a question online, then go back and write code till he hit another barrier, and so on.
I responded to him, “You would never design a software system using such an undisciplined and ad hoc methodology. Why do you tolerate your learning experience to be designed in that manner?”
The programmer didn’t appreciate that each person must bring some expertise to benefit from experimentation and collaborative learning. Modern technical training, with its heavy emphasis on both experimentation and collaboration, draws heavily on John Dewey’s classic theories of learning as a dialectical process between the learner and her environment—the more prepared the learner is, the greater heights she can attain.
You probably remember rejecting a book as boring and irrelevant, only to come back and embrace it later after a phase of personal growth. Collaborative forums can foster this upward spiral. The techniques in this book help you not only improve the forums, and use them to improve your documentation, but also use the forums to prepare readers to benefit from the documentation.
So, what can you offer as a writer or other professional to foster this upward spiral and give readers the best available educational experience?
Most readers stick to familiar ways of communicating. The hoary old mailing list format, and even newer documentation models such as wikis, fail to exploit the power of user contributions. It takes work to create a system that efficiently accepts, formats, and disseminates information provided by public participants. And those are just the start. Popularity ratings, tagging mechanisms, and sophisticated search options can dramatically increase documentation’s usefulness as well. Take the lead to develop and train your community to use a powerful interactive educational system, and their productivity will soar. You’ll probably generate more interest in your professional contributions along the way.
Everybody can use an editor. Routine proofreading for grammar and consistency aren’t usually important for casual online contributions, but anything longer than a couple of paragraphs could benefit from a look at its purpose, structure, and information gaps. A small investment of professional time can make the document much more useful. Remember that you are a collaborator, so you need to work dialectically with the author to find the best approach to the document. And you’ll both learn something from the process.
A big part of writing is going back to straighten out a document. Because online documents tend toward drastic fragmentation, and reflect many different voices, the role of a professional writer and editor faces a steeper challenge but a concomitantly larger benefit to the overall site. You can spend time organizing documents and creating pathways through them, creating links, and putting up portal pages. Don’t feel shy about intervening directly in the documents themselves, by adding introductions and transitions and changing headings to indicate more accurately what’s inside the document.
Most people have something to contribute, but they wait to be asked. Once asked, they’re more than happy to help out. You need to determine where the needs are and who can fulfill them. You also need to offer support for them to create a document of high quality and promote the result so they feel their work is rewarded by exposure.
Your own documentation should be the flagship for the community. You can use community input to improve it and add some research of your own to take it to the next higher level of community trust.
Reading Anne’s book brought me a number of satisfying moments. She quite properly recognizes the importance of both documentation and search: the notion that both availability and findability are fundamental documentation requirements. I’m glad she attacked the stance that we serve our project best by always presenting it in a positive light. She understands the role of audio and video media in the current educational landscape. And she even draws insight from one of my favorite and chronically under-appreciated research projects, John Carroll’s Minimalist documentation.
The book is not as tightly organized or carefully paced as an ideal expository text would be. This is because Anne offers so much, has so few sources to point to when making her core points, and is covering fast-changing areas whose participants offer new insights literally every week. She manages to pull it all together.
I think the author of a foreword is expected to say he “couldn’t put the book down ’til it was done.” I’m afraid I can’t offer Anne the opportunity to make that boast. In fact, I was constantly pulled away from her book by her references to fascinating documents that added extra fodder to her argument or provided new perspectives. I’m sure Anne’s web site will host equally enticing content. Let this book be an anchor for your exploration of collaborative document production, so that your own documents can be anchors within your clients’ learning ecosystem.