/
2012-02-24-why-dont-technical-writers-use-wikis-or-do-they.html
82 lines (79 loc) · 15.5 KB
/
2012-02-24-why-dont-technical-writers-use-wikis-or-do-they.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
---
layout: post
title: Why don't technical writers use wikis — or do they?
date: 2012-02-24 01:26:50.000000000 -08:00
categories:
- technical-writing
- wikis
tags:
- collaboration
- confluence
- guest posts
- sarah maddox
- WritersUA
status: publish
published: true
---
{% include toc.html %}
<p>The following is a guest post by Sarah Maddox, a technical writer at Atlassian.</p>
<p><a href="https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/2009/04/orangebar.png"><img class="alignnone size-full wp-image-9119" style="border: none;" title="orangebar" src="https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/orangebar.png" alt="" width="300" height="3" border="0" /></a></p>
<p><figure><a href="https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/SarahMaddox-January2012thumb.jpg"><img class="size-thumbnail wp-image-10643" title="Sarah Maddox guest post on wikis" src="https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/SarahMaddox-January2012thumb-150x150.jpg" alt="" width="150" height="150" /></a><figcaption>Sarah Maddox</figcaption></figure></p>
<p><em>In a recent conversation, Tom mentioned that he's been pondering this question: "Why, in a time when collaboration is more important than ever, do wikis still remain mostly unused as a help authoring tool in tech comm departments?" Tom asked me to join his ponderings and write a guest post on the topic. Thanks for the invitation and the thought-provoking question, Tom!</em></p>
<p>I started by thinking about the question itself. Do we know how many people use wikis as a help authoring tool, and what do we mean by help? For this post, let's say that "help" means technical documentation in general, which I think is the thrust of Tom's question.</p>
<h2>Is it true to say technical writers don't use wikis?</h2>
<p>Serendipitously, two bits of news appeared just as I was about to put my ponderings to paper.</p>
<p>The first was a guest post by David Kowalsky on <em>The Content Wrangler</em>: <a href="http://thecontentwrangler.com/2012/02/07/collaborative-authoring-and-communication-tools-help-writers-editors-smes-work-together/">Collaborative Authoring and Communication Tools Help Writers, Editors, SMEs Work Together</a>. The post discusses a number of collaboration tools, yet wikis get only a very brief mention: "Wikis are becoming more widespread." That's it.</p>
<p>So, that post lends strength to the surmise behind Tom's question. Wikis are only barely in the picture.</p>
<p>Then another bit of news popped up – the results of the <a href="http://www.writersua.com/surveys/skillstech12/index.html">2012 WritersUA Skills and Technologies Survey</a>. When conducting the survey, WritersUA provided a list of popular user assistance technologies and asked the respondents to value the importance of those technologies in their current development efforts. The <a href="http://www.writersua.com/surveys/skillstech12/index.html">technologies section</a> of the survey shows that 28% of respondents rate wikis very highly.</p>
<p>28% is not to be sneezed at.</p>
<p>One respondent noted:</p>
<p>Ask again next year and the landscape will have changed dramatically. We intend to migrate from Webhelp to a wiki/kb delivery model and I can't wait!</p>
<p>WritersUA also provide details of <a href="http://www.writersua.com/surveys/tools12/index.html">specific tools</a>, where wikis are mentioned quite a bit too. Try searching the page for "wiki" and "confluence" (because the latter is mentioned without the word "wiki").</p>
<h2>Rephrasing the question asked in this post</h2>
<p>Based on the WritersUA results, I've changed the question slightly. Instead of asking why wikis <em>remain mostly unused</em> as a help authoring tool, let's ask, "Why don't <strong>more of us</strong> use wikis as a help-authoring tool?" It's an excellent question to address in a blog post. There are likely to be some passionately-held opinions and some great stories around the use of wikis, experimentation with wikis, trials and tribulations as well as thrills and conquests. Bring 'em on, folks.</p>
<h2>So, why don't more of us use wikis as a help-authoring tool?</h2>
<p>I think the crux of it is this: each type of tool makes one set of functionality easy, and supplies other sets of functionality via add-ons or processes that are less comfortable.</p>
<p>Wikis excel at collaboration, notifications and monitoring of updates, integration with other web apps, sharing content, and social features like networks of colleagues and status updates. They also provide instant gratification, by publishing updates as soon as you click save. (That's the default behaviour, though in some wikis you can configure a workflow to delay publication.) Wikis are great at publishing good-looking documentation with a minimum of fuss and bother.</p>
<p>Wikis are not so good at version control across a documentation suite, single source publishing, or topic-based authoring. They were not originally designed with that focus in mind. But there are add-ons currently available that extend the wiki functionality in the directions we need, and there are more add-ons under development that will do it even better.</p>
<p>Dedicated authoring tools excel at single-source publishing. The newer tools focus on structured authoring. Many of them either have their own version control system or integrate with the same source control tools used to store code. On the other hand, such tools are designed for use by a small, dedicated team. They tend to lock out people who are outside the technical writing team, due to license costs and/or technical complexity. Collaboration is therefore difficult. There is a publishing step between updating the content and making it visible to readers, which may require a delay of some hours until the documentation can be built. Some tools have introduced social features such as commenting, but the published documentation suite does not offer the people-focused experience that a wiki offers.</p>
<p>Can you have all the features in one tool? That would be great, and the need is there. I don't know of a tool that elegantly satisfies all requirements. Not yet. But there are some promising developments underway. Because I'm so deeply involved in the world of wikis, I know of the excellent plugins and add-ons under development to add workflow, single sourcing and sophisticated version-control to a wiki. I'm sure that people reading this post know of the new collaborative and social features being introduced into other tools.</p>
{% include ads.html %}
<h2>Weighing up priorities</h2>
<p>Technical communication is a broad and diverse field. There are as many ways of categorising what we do as there are environments that we work in. Not surprisingly, there are as many ways of prioritising our needs too. It's up to us to choose the tool that fits our requirements. Each tech comm team has to weigh up the priorities, based on the aims of our organisation, team and audience.</p>
<p>But here's the thing: We can help by knowing the capabilities of each tool, and educating our organisations about the benefits of each.</p>
<p>It can be hard to know the capabilities and functionality of a wiki, and especially the capabilities that are useful to technical communicators. Wikis are constantly evolving. Sometimes additional functionality is available via installing a plugin, but it's difficult to find that information. Or perhaps the features are there in the wiki, but are not packaged and labelled as something useful for technical documentation. For example, wiki documentation may talk about spaces, watches, notifications, RSS feeds. We need someone who is already in the know, to describe the features and show us how to use them in our workflow.</p>
<p>Maybe those of us who use wikis are just not especially vocal about it. Here's a suggestion: Wiki huggers need to jump up and shout it out: <strong>Kiss my wiki</strong>.</p>
<p>A lot of it comes down to communication and help.</p>
<h2>Difficulty harnessing the power of the crowd</h2>
<p>Collaboration is a consummation devoutly to be wished. (OK, maybe not for all documentation suites, but let's assume that we want collaborative authoring now since that's the topic of this post.) But it's not easy. Collaboration can be a messy business. This may be one reason why technical communication teams have not yet implemented a wiki-based solution. They're looking for success stories. Has anyone successfully opened up the product documentation to updates by external authors? How about letting everyone in the company update the docs, or even company partners and community developers. How about the general public?</p>
<p>This is a broad topic. For my team, I can say that we are making it work, that it's fun and challenging and rewarding, and that we constantly re-evaluate the way we do things to see if there may be a better way. Our documentation is continuously being updated by subject matter experts (developers, support engineers, marketing engineers, product managers and even a CEO or two). We also have a group of around 50 community authors who update pages every now and then, particularly in the developer-focused documentation.</p>
<p>This post would become very long if I included guidelines on how to manage the updates by everyone. Instead, here are some pointers about the things to consider:</p>
<ul>
<li><strong>Permissions:</strong> The tool you choose must allow you to define groups of people (technical writers, company staff members, community authors, etc) and to assign permissions to each group.</li>
<li><strong>Monitoring and notifications:</strong> You must be able to subscribe to an area of the documentation, and receive notifications whenever someone updates a page.</li>
<li><strong>Copyright and intellectual property:</strong> You will need to display a suitable copyright license (we use Creative Commons by Attribution) on all the pages, so that contributors and readers alike know their rights. It's also a good idea to ask contributors to sign an agreement, signifying that they understand the intellectual property arrangements for the content that they contribute. <a href="http://confluence.atlassian.com/display/ALLDOC/ACLA+v2.0">Our agreement</a> is based on the Apache Contributor License Agreement.</li>
<li><strong>Encouraging people to contribute:</strong> It's safe to say that you won't be deluged with updates. Instead, invite people to update the documentation and keep telling them how much you appreciate their contributions. The experience is rewarding and enlightening. Every day you'll learn new things about your readers and the way they use your products.</li>
<li><strong>Style guides, templates and structure:</strong> It's a bit of a balancing act. Too much structure can deter contributors. Yet everyone appreciates some guidelines. Templates are very useful, especially in getting rid of that dreaded empty page that needs filling. A light style guide, informative rather than prescriptive, is useful to external as well as internal authors.</li>
</ul>
<p>The above points are some of the things to consider when allowing other people to update the documentation pages. There's more to think about when you allow people to add comments to the pages. For example, the volume of contributions in comments can be overwhelming – people are more likely to add comments than to update a page. You'll need to ensure that management understands the number of people required to handle such input, and the different types of comments that you will receive. In our experience, most comments are calls for help rather than points about the documentation itself. It's therefore useful if the support team and developers can help respond to the comments too.</p>
<p>The most rewarding thing of all is that people help each other. Someone asks a question, someone else answers, and everyone benefits, without the technical writers needing to intervene at all.</p>
<h2>Customisable look and feel</h2>
<p>Technical communication teams need to add a brand to the documentation (logos, colours, fonts). They may want a tripane help system or something that looks closer to a website.</p>
<p>In the early days, all wiki documentation looked the same. Bland, black and white with blue links, and if you were lucky a left-hand navigation bar with a table of contents. Above all, there were no rounded corners to be had for love nor money.</p>
<p>Things have moved on, and wikis allow a fair bit of customisation via themes (skins), CSS, replaceable logos, and more. But I think many people still hark back to that era of prosaic look and feel when they hear the word wiki. Here are some wiki sites with a sophisticated look:</p>
<ul>
<li><a href="http://docs.splunk.com/Documentation">splunk>docs</a></li>
<li><a href="https://developer.atlassian.com/">Atlassian developers</a></li>
<li><a href="http://www.pnims.org/display/home/Home">PNI</a></li>
<li><a href="http://www.wowwiki.com/Portal:Main">WoWWiki</a></li>
<li>Any more? If you know of other pretty wiki sites, please add a link in a comment.</li>
</ul>
<h2>What's in a name?</h2>
<p>A couple of times I've heard people say that the name "wiki" puts them off. The word sounds trivial, not suited to the powerful tool they're looking for. It doesn't reflect the multifunctional tools that wikis have become. Other people say that "wiki" sounds old and dry – very 90s.</p>
<p>Some wikis have changed their description to "collaboration platform" or something similar. MindTouch, for example, is based on DekiWiki. At the moment, the <a href="http://www.mindtouch.com/">MindTouch website</a> calls its platform the "Social Help Center with Knowledgebase and Help System". (Note that David Kowalsky does mention MindTouch TCS <a href="http://thecontentwrangler.com/2012/02/07/collaborative-authoring-and-communication-tools-help-writers-editors-smes-work-together/">in his post</a> on <em>The Content Wrangler</em>.) At Atlassian, there are mutterings every now and then about what to call Confluence. Should the word "wiki" appear on the website, we ask ourselves earnestly? The <a href="http://www.atlassian.com/software/confluence/overview">product page title</a> currently says "Content and Social Collaboration Software".</p>
<p>My 2c? I like the name "wiki". It's simple and cute. It retains the history going back to the very first wiki, invented by Ward Cunningham and opened to the world in 1995: <a href="http://c2.com/cgi/wiki?WelcomeVisitors">WikiWikiWeb</a>, also known as just plain Wiki.</p>
<p>And you know what? "Wiki hugger" sounds so much better than "collaboration platform hugger"!</p>
<h2>Honk, beep and wave</h2>
<p>So, honk if you're using a wiki for technical communication. Beep if you're considering it. Wave if you're not. I'd love to hear what everyone thinks about the points in this post. And tell me what I've missed!</p>
<h2>About Sarah</h2>
<p><em>Sarah is a technical writer at Atlassian, makers of Confluence wiki and other software tools. She has 14 years of technical writing experience, the last four of them on a wiki. Sarah's new book is about developing documentation on a wiki: <strong>Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication</strong>. It's also about technical communicators. And chocolate. The book covers the points mentioned in this blog post, and a lot more. The book is published by <a href="http://www.xmlpress.net/publications/chocolate/">XML Press</a>, and is available on <a href="http://www.amazon.com/Confluence-Tech-Chocolate-Sarah-Maddox/dp/1937434001">Amazon.com</a> and <a href="http://www.barnesandnoble.com/w/confluence-tech-comm-chocolate-sarah-maddox/1108812996?ean=9781937434007">Barnes & Noble</a>. Sarah's blog is at <a href="http://ffeathers.wordpress.com/">http://ffeathers.wordpress.com</a>.</em></p>