Wikis and other forms of social media are turning tech documentation and communications into a two-way conversation.
Social media is changing communications, in ways that are both good and bad--but always interesting.
I recently spoke to a local chapter of the Society for Technical Communication, made up of people who write documentation, create help systems, edit knowledge bases, and (these days) work to make user interfaces more self-explanatory. I urged them to pay attention to how social media is changing the very nature of communications--much as the invention of writing, or of television did, rewiring our brains along the way--"because I know it's changing my profession and I'm pretty sure it's changing yours, too."
Technology journalism is not so different from that other brand of technical communication in the sense that we both aim to make complicated information clear. My wife is an STC member from a couple of past gigs at software companies and some more recent consulting work, and I've occasionally done documentation and technical marketing writing. I also maintain a couple of WordPress plugins, which are documented in a series of blog posts that I have to revise on a regular basis because people complain when my explanations are unclear.
The Web in general has democratized the world of publishing, and social media only more so. Professional communicators must work harder because they're now in competition for attention with the voice of the crowd, blurring the distinction between author and audience. As a journalist, I can be excited about the dynamics of blogs and social media sites but still worry about them siphoning off of ad dollars from professional publications. Similarly, STC members must wonder whether it's to their advantage to organize documentation in a wiki that anyone can add to or edit.
On the other hand, denial is not a great strategy. The challenge for the professional communicator is to contribute at a higher level, welcoming community involvement and building on it. For the technical writer, that may mean doing less writing and more curating of content--for example, identifying and promoting the best wiki contributions, correcting errors, clarifying unclear language, adding illustrations, and improving organization.
I also cribbed from presentation by Jennifer Zickerman of the Mozilla Thunderbird project, which among other things covers tactics for "turning complaints into contributions." To run a successful documentation community, you need to beware of "literary critics and grammar Nazis," she warns. "Better to lose one knowledgeable but nasty editor than 10 enthusiastic contributors."
The wiki style of documentation wins its greatest acceptance in the open source world, where community-contributed documentation is often the alternative to no documentation at all. In return for gathering broader community contributions, it comes with some trade-offs, such as the potential for loss of control, or even vandalism and spam. More tightly controlled documentation can still benefit from community contributions, such as comments at the bottom of the page or in related discussion forums.
Howard Schwartz, senior vice president of content technologies at SDL, says that technical writers need to embrace community content whether or not they go to the extreme of wiki-style editing. Writers who have traditionally been separated from their audiences are now seeing the walls coming down--and once they get used to the change, they ought to find that exciting, he said.
"Tech writers have been humanists who ended up in the tech world and have been part of R&D, with their work thought of until fairly recently as part of the product release cycle," Schwartz told me a few months ago. But documentation no longer just gets stuffed in a box and shipped. Now that much of it is available online, it's become common for people to read the documentation before they buy the product--making it more important than ever to have clear documentation that makes a product inviting rather than intimidating.
SDL makes content management systems targeted at scenarios like documentation that must be translated into many languages and single-source published into both printed and digital forms. SDL Live Content is a version that aims to gather community comments on documentation and route them back to the authors to incorporate into future revisions. SDL has published a series of position papers, including one on "The Death of Technical Documentation As We Know It," arguing that documentation can no longer be delivered as static content but must always be evolving.
A conference presentation video and related blog post from Atlassian's Sarah Maddox covers some of the ways technical communicators can embrace social and community content. One of Atlassian's products is the Confluence social software, so naturally this is something they're attuned to. Yet she explains that Atlassian applies different community collaboration rules for different kinds of content. Developer documentation is managed in a wiki where anyone with an account can post or edit content, and that works well for generating lots of code samples and usage examples. For the core product documentation, they also make some members of the community editors, but those people have to be vetted first and they have to sign an agreement on their rights and responsibilities. Beyond that circle, other users can post comments on the formal documentation, and the editorial team monitors those comments to see if there are things they need to add or change.
Atlassian has also taken to tweeting out its release notes, so that each significant or improvement or bug fix goes out to Twitter followers in a form that they can easily retweet or comment on. Each of the tweets includes the same hashtag, so readers can click on any one of those notes to see the whole series. Of course, anyone can also hijack that tag to add their own comments. "Is there a chance that somebody will say something nasty in your release notes? Yes there is. That's actually the point, and if that happens you need to respond to it," Maddox says in the video.
Does all this community activity devalue the contribution of the professional writer or editor? Certainly, that's the danger. Professional communicators must show that by editing and curating and learning from user contributed content, they can produce a better organized and more valuable product. They need to show how they create order out of chaos.
The Enterprise Connect conference program covers the full range of platforms, services, and applications that comprise modern communications and collaboration systems. It happens March 25-29 in Orlando, Fla. Find out more.
InformationWeek Tech Digest August 03, 2015The networking industry agrees that software-defined networking is the way of the future. So where are all the deployments? We take a look at where SDN is being deployed and what's getting in the way of deployments.