Social Documentation and the Future of Technical Writing

By Michael Lykhinin

Technical writing is on the brink of paradigm shift from one-sided, didactic, expert-driven user documentation to integrating user-generated content, collaborative communication, and the power of communities. Today, documentation teams can and should utilize Web 2.0 approaches to capture user-generated content and user information using external and internal user communities, wikis, blogs, forums, and social media platforms APIs.

Web 2.0 did not only provide users with opportunities to collaborate in knowledge creation and interact directly with information, authors, and peers, but also to process and filter information through online conversations. At this point, there are more conversation tools available to users than ever in history: blogs, wikis, forums, social networks, to name a few. Utilizing these tools, technical writers can move beyond user-centered documentation to personalized co-created social documentation through starting, directing, and curating user conversations and facilitating community knowledge and content creation. Web 2.0 provided new technology options, but the concept of co-creation is not new: in the 1800’s The Oxford English Dictionary was created and updated as a community effort by a group of volunteers. The key differences today are the speed and the volume of information being accumulated and processed.

In the mid-2000’s, Harry Miller of Microsoft pondered that user guides could potentially evolve to read like an instant messaging conversation: real-time questions and answers, tailored to fit specific context or situation. Approaching documentation as conversation inevitably leads to getting to know users really well and helps them to perform. Although not as instantaneously as Siri, IM chat bots, or fellow Twitter users, social documentation can potentially anticipate questions and provide answers responsively. Anne Gentle recommends that technical writers start thinking about documentation and user assistance as a multi-channel communication device instead of concentrating on single-sourcing methods. After all, according to Ginny Redish, technical communication, just like Web 2.0, is all about helping users get just what they need, when they need it, in the amount they need, as quickly as possible.

Thanks to Web 2.0, today almost everyone is an author and a publisher. In 2010, we collectively uploaded 13 million hours of video to YouTube, Flickr reported hosting 5 billion images, and Wikipedia had over 3.5 million articles in English. Altruism and passion for self-expression, combined with web publishing systems that ensure low barriers to entry, lead to a whole new way of working and writing. Regardless of background, education, and training, more and more people become providers of technical information on the Web outside of their regular employment. In 2008, Daren Barefoot noted that today everyone is a technical writer: people formerly known as audience are already documenting your products in ways and to an extent you could never hope to cover yourself or with a team of technical writers.

To execute a successful social documentation strategy, technical documentation teams need to learn how to architect and foster user communities and then how to incorporate user-generated content into their workflows. Fortunately, technical communicators already have translatable knowledge and skills – e.g. excellent communication, concise writing, good information design, planning, etc. to become effective community information librarians and conversation enablers/facilitators. The roles technical writers can play in external, or public, and internal, or “owned”, user communities may vary quite significantly.

In external communities, especially if they are fairly small, technical writers can join and learn what motivates people to use their product, who their users are, whether they are passionate about the product, what kind of issues they may be experiencing, as well as suggestions, resolutions, and best practices they may be sharing. When working within an external community, it is important to know whether your organization is already talking to its members and to match your contributions to the community with your role in the company. From the ethics perspective, it is imperative to disclose your affiliation and potential conflicts of interest that come with it. In most cases, it is also not advisable to try to take on leadership or management responsibilities, at least not until your social network within the community takes shape and your reputation solidifies.

In internal, or “owned”, communities, technical writers can wear many hats and perform diverse roles like community manager, community leader, creator of guidelines and central purpose, community trainer, content curator, content seeder, motivator, enabler, instigator, moderator, arbitrator, and expert, to name a few. Generally, for larger technical documentation teams, it is recommended to have several technical writers share specific subsets of community roles, based on their level of experience with the product, leadership ability, and communication style.

Needless to say, no social documentation initiative should start without developing a comprehensive strategic plan for community engagement, community/user research, and community content integration as well as creating detailed community engagement and technology roadmaps. Anne Gentle identifies four phases of community engagement: from simply listening to participation in conversation to sharing content to, finally, creating “owned” community or offering a platform. Similarly, the technology roadmap for social documentation content creation and re-use can consist of three phases:

•Manual content and user information collection from external communities/platforms for use in user documentation development.
•Offering an “owned” platform for and cultivating a community as part of user support and user documentation development effort.
•And, finally, automated content and user information aggregation from external and internal platforms and communities for use in user documentation and product development.

Based on the technical documentation team’s needs and CMM stage, you can choose the best fit from the plethora of social technology options available today: public social media platforms, including FB, Twitter, Pinterest, and the like; private community platforms similar to Ning, Telligence, etc.; various blogs, discussion forums; and, last but not the least, wikis.

Integrating social media platform APIs into your web-based documentation does not only create an efficient content distribution and feedback mechanism, but can also help documentation teams to capture detailed user information and create user personas with previously unavailable scientific and statistical precision. Evaluation of content by a community of users can serve as an approximation of the academic peer-review process. It may start with a verdict on whether the content solves the problem quickly and end with sophisticated suggestions for improving its consistency, organization, findability, and compliance with the latest standards or best practices. A higher feedback score or search ranking can serve as a rough yet effective indicator that the content is helping more people.

In addition to creating and maintaining a product Facebook page or group, by integrating Open Graph API into you technical documentation you can make your content a rich object in a social graph. This will enable your technical documentation team to push highly customized content to your “friendly” users as well as to potentially gain access to their detailed “basic information”, subject to profile privacy settings. You will be able to see a demographic breakdown of the Open Graph data by gender, content source, language, country, published actions, content impressions, content likes, timeline content unit impressions, and much more. Armed with this data, your company can customize user documentation, in-context user assistance, software features, and, of course, marketing materials based on who your users are.

Twitter and other micro-blogging platforms enable technical documentation teams to communicate and collaborate with their users and customers in real-time. You can quickly share micro content and updates with users who are interested in your product or company, or gather instantaneous intelligence and user feedback, as well as develop personal relationships with your current and potential customers. Twitter and similar platforms can be particularly useful for crowdsourcing answers to simple technical, design, or usability questions.

As the oldest online social engagement tool, discussion boards and forums remain a valuable relationship-building and information dissemination/gathering tool. Joining forums and contributing to discussions has always been an excellent way for technical writers to establish themselves as part of the community. Today, many forum tools feature sophisticated notification, rating, and moderation systems. Many forums have point systems for earning ranks or freebies. In some forums you can rank answers or fellow members by how helpful they have been to you.

Since their appearance in mid 1990’s as developer collaboration tools, wikis instantly became a perfect platform for living, breathing, changing documentation. For technical documentation teams, wikis offer an exciting opportunity to engage users and get their perspective on tasks, procedures, instructions, and scenarios. Wikis became one of the first examples of living social documentation due to their ability to incorporate new information or feedback into their content.

As the concept of social documentation began to draw more and more attention from technical communication and software development communities, a number of vendors rushed to stake out the emerging market.

In 2010, MindTouch announced the first release of their Social Documentation Solution – a web-based integrated social authoring, publishing, and community engagement environment. As a sort of private wikipedia for enterprise, this software product, largely based on the company’s earlier open-source collaboration platform, enables end users with little or no technical knowledge to contribute and co-edit reference guides, tutorials, FAQs, files, images, and videos. It also provides a highly specialized set of community management tools such as curation analytics, community content moderation, and permissioning system allowing documentation content to be winnowed down to specific users or groups.
In one of the most bombastic product launches of 2011, SalesForce introduced their vision of convergence of customer support/user documentation, customer relationship management, and sales platforms – the Social Enterprise. Based on the premise of making every interaction social, SalesForce claims that their new platform is a game-changer when it comes down to enabling conversations and collaboration between companies, their employees, and customers. The Social Enterprise platform is expected to allow organizations to deliver social customer service and fresh, relevant content in real-time everywhere users can access it. The new platform does not only promise to engage users, but also to analyze conversations and interactions relevant to the products across social media.

While social technical documentation is a fairly new concept, many forward-looking technology companies and open-source projects have been creating communities and integrating community-generated content into their user support ecosystems since early 2000’s. Among social documentation success stories are Adobe Labs, Apache documentation, eBay wiki, Microsoft’s MSDN, Sun’s OPenDS documentation, Cisco’s customer support wiki, and OpenStack manuals, to name a few. These communities and documentation sets can serve both as an example and inspiration to technical documentation teams and technical writers charged with implementing social documentation initiatives in their organizations.

Social documentation, both as methodology and philosophy, promises to change the way technical writers work and offers new and exciting opportunities to those technical documentation teams who can take advantage of them. If you are not sure where to start, what your role may be, what technologies to use, or if this is just another fad, you may be interested in joining the Docs 2.0 group on LinkedIn at http://linkd.in/Hy4WpY .

References:

•Anne Gentle, Conversation and Community: The Social Web for Documentation (XML Press, 2009).

•Darren Barefoot, “Everyone’s a Technical Writer” (talk at DocTrain West, Spring, 2008).

•Harry Miller, “The IM Model of Tech Writing,” MSDN Blogs: Visual Communication and Design, July 16, 2007, http://blogs.msdn.com/harrymiller/archive/2007/07/16/the-im-model-of-tech-writing.aspx.

•Janice (Ginny) Redish, Letting Go of the Words: Writing Web Content that Works (Morgan Kaufmann, 2007).

•“MindTouch: Product,” last accessed August 20, 2012, http://www.mindtouch.com/product/.

•“The Open Graph Protocol,” last accessed August 20, 2012, http://ogp.me/.

•“The Social Enterprise Solution,” last accessed August 20, 2012, http://www.salesforce.com/solutions/.

About the Author:
Michael Lykhinin is a Web 2.0, information architecture, content and knowledge management, social media, and technical documentation strategist in Orlando, FL. He currently serves as director at OGI, Inc. (ogisolutions.com) – a small technology consultancy offering a wide array of services: from web development, social media marketing, search engine optimization, information architecture, and content management to software documentation, localization, and translation. Most of his time Michael spends exploring new trends in web technology, social media, and technical communication and their impact on business and higher education. Michael has developed an automated open social web/online software help and documentation model (U.S. patent pending) and is the manager of the Social Documentation – Docs 2.0 group on LinkedIn. As a second job, Michael tries to be a parent and a friend to a teenage son, a beautiful cat, and a noble puppy. He can be reached by email at michael@ogisolutions.com.