Why don’t technical writers use wikis — or do they?

The following is a guest post by Sarah Maddox, a technical writer at Atlassian.

Sarah Maddox

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!

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.

Is it true to say technical writers don’t use wikis?

Serendipitously, two bits of news appeared just as I was about to put my ponderings to paper.

The first was a guest post by David Kowalsky on The Content Wrangler: Collaborative Authoring and Communication Tools Help Writers, Editors, SMEs Work Together. The post discusses a number of collaboration tools, yet wikis get only a very brief mention: “Wikis are becoming more widespread.” That’s it.

So, that post lends strength to the surmise behind Tom’s question. Wikis are only barely in the picture.

Then another bit of news popped up – the results of the 2012 WritersUA Skills and Technologies Survey. 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 technologies section of the survey shows that 28% of respondents rate wikis very highly.

28% is not to be sneezed at.

One respondent noted:

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!

WritersUA also provide details of specific tools, 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”).

Rephrasing the question asked in this post

Based on the WritersUA results, I’ve changed the question slightly. Instead of asking why wikis remain mostly unused as a help authoring tool, let’s ask, “Why don’t more of us 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.

So, why don’t more of us use wikis as a help-authoring tool?

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.

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.

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.

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.

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.

Weighing up priorities

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.

But here’s the thing: We can help by knowing the capabilities of each tool, and educating our organisations about the benefits of each.

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.

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: Kiss my wiki.

A lot of it comes down to communication and help.

Difficulty harnessing the power of the crowd

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?

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.

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:

  • Permissions: 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.
  • Monitoring and notifications: You must be able to subscribe to an area of the documentation, and receive notifications whenever someone updates a page.
  • Copyright and intellectual property: 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. Our agreement is based on the Apache Contributor License Agreement.
  • Encouraging people to contribute: 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.
  • Style guides, templates and structure: 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.

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.

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.

Customisable look and feel

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.

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.

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:

What’s in a name?

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.

Some wikis have changed their description to “collaboration platform” or something similar. MindTouch, for example, is based on DekiWiki. At the moment, the MindTouch website calls its platform the “Social Help Center with Knowledgebase and Help System”. (Note that David Kowalsky does mention MindTouch TCS in his post on The Content Wrangler.) 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 product page title currently says “Content and Social Collaboration Software”.

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: WikiWikiWeb, also known as just plain Wiki.

And you know what? “Wiki hugger” sounds so much better than “collaboration platform hugger”!

Honk, beep and wave

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!

About Sarah

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: Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. 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 XML Press, and is available on Amazon.com and Barnes & Noble. Sarah’s blog is at http://ffeathers.wordpress.com.

Madcap FlareAdobe Robohelp

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • https://shwetahardikar.wordpress.com/ Shweta Hardikar

    Honk Honk!:)
    We use confluence wiki for all our documentation (I will call it wiki only). We even have one version just for Dev and QA teams where they put their documentation, updates, team status, team information etc. That serves as a repository and a knowledge base for others.
    It is fun, people like to leave comments on wiki pages, it is great for reviewing and getting feedback. We are still in nascent stages so haven’t really explored all of it, yet we are happy about it!

    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Shweta

      That’s interesting! Do you have two separate wiki sites, one for the Dev and QA teams, and another for the documentation? I’m guessing the first is for an internal audience only, whereas the second is for viewing by customers too.

      Where I work, we do the same. The content on the two sites is very different, and so is the way people use the information. The internal wiki is an intranet. People post their updates and guidelines, much as you mentioned. The external wiki is primarily for documentation. It’s interesting to see the way people relate to the content on both sites. On the internal wiki, people tend to write a page or blog post, but seldom come back to update it. Also, the content is much less structured. On the external wiki, of course, we add a lot of structure and update the content regularly. I find it interesting to see the requirements the different groups of users have for the wiki.

      Cheers, Sarah

      • http://idratherbewriting.com Tom Johnson

        I once read that social media formats (such as wikis) enjoy their greatest use behind corporate firewalls. I think people might be much more inclined to edit an internal corporate wiki than an externally facing one.

      • https://shwetahardikar.wordpress.com/ Shweta Hardikar

        Absolutely Sarah.

        What we have as an internal wiki is meant for developers and QA where they write about the functionality, provide samples, examples etc. This wiki is used by all the dev, QA, managers, architects to discuss, plan, and keep everyone updated about the functionality-based developments. As far as comments and updates are concerned, Yes, comments are provided by anyone in the team. Since we follow Agile, we have the content updated during each release cycle.
        We (technical writers) use this as a chief source of information. I find this as a best source as it is constantly updated, I can watch the pages for updates (so no chance of the developer missing to inform me abt it), and can leave a comment which is almost certainly addressed.
        The external wiki is a customer-facing one where all structured information is present. Our customers see this wiki, and can leave a comment here.

  • DiSc


    In a sideproject I use a wiki for documentation – DokuWiki, specifically. In my 32 minutes of daily free time I need to be able to do things quickly, and a wiki ensures that all I do is immediately there for people to see.

    However, yes, counterindications abound. No single-sourcing, at least not without a somewhat lengthy procedure. No topic-based authoring. No IDE, so more errors, although you can conjure up a solution with Eclipse, a FTP client, a backup job and a lot of patience. Do you need to replace all occurrences of a word/phrase/value etc? Good luck with that. I think wikis also scale pretty badly as the project grows – Docbook is great in that respect. As an authoring tool, a wiki is severely underpowered.

    On the positive side, a wiki does come in handy if //SMEs put content into it//, in their charming, messed-up, barely-literate, border-line autistic kind of way. And then you as a technical writer step in and put the pieces together, fix spelling, syntax, apply punctuation, a consistent style, capitalization, remove circular reasoning, and so on.

    With some effort, Dokuwiki can be brought to do almost anything. There are plenty of plugins that considerably extend its capabilities. And if Confluence is as good as Jira, I bet it is a very good tool.

    Back to the original question – why don’t we use wikis more? – I think the answer is that

    1) a wiki is not enough of an authoring tool for technical writers, and too much of it for SMEs. TW want to have more features, SMEs do not care about formatting and structure – you can, after all, do it with Word/Google Docs. And everybody knows how the product works anyway, so why waste time writing it down, right?

    2) both our professions (TW and, say, programmers) thrive on secrecy and try to keep outsiders out – to preserve our salaries, at least. We constantly try to make our work look more difficult than it is, invent standards, jargon, coming-of-age rituals (Open Source projects, anyone?) and so on. Wikis are built on the opposite premises: open communication.

    3) as it follows from the two previous points, I think wikis can really make a difference if the border between the two professions blurs and you have, in my field at least, programmers/writers, with job descriptions, work schedules and processes matching that.

    My 2 cent,


    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo DiSc

      What a great comment. There’s lots of good information there. I’d love to know more about DokuWiki. As its name implies, it was designed with documentation in mind!

      This is a really interesting point: “a wiki is not enough of an authoring tool for technical writers, and too much of it for SMEs”. I think you’re right. As technical writers, we keep asking for more and more features to be built into our tools. In fact, one of the great things about a wiki as a platform is that you can do just that: install plugins and add-ons to extend the functionality. But our SMEs just want something that works.

      The philosophy of a wiki is to keep it simple. When I first started working on a wiki, it was like a breath of fresh air. Just write the words, without needing to worry too much about the presentation or about building the documentation. Then I started noticing the missing functionality. The temptation is to ask for it all to be put into the wiki. But I think we need to be careful about that. It’s a design decision that needs a lot of careful thought.

      The best would be if the wiki could offer a “simple” experience to the people who just want to write some words then go back to their day jobs, and a more technical experience to those of us who need that. And of course, the content needs to survive the switch from the one type of user to the other and back again.

      Cheers, Sarah

      • http://idratherbewriting.com Tom Johnson

        Good points about the balance between simplicity and functionality. I favor simplicity. I’ve found that, at least for applications I document, there isn’t a huge need for single sourced manuals for each role, or a print and mobile and webhelp version of the content. People are just interested in accessing up-to-date, accurate information about a product. I know that you can get more techie with Mediawiki if you want. For example, their table code can be a little intimidating, as can the code for templates. But the more complex the endeavor becomes, the less likely novices are to edit the content. The goal is to invite collaborative editing/authoring, so simplicity has to remain a priority.

    • Rio

      Thank you for the heads-up re Docu-Wiki. It looks like it might be the middle ground I’ve wanted between MediaWiki and traditional documentation software.

      • http://idratherbewriting.com Tom Johnson

        I’ve used Docuwiki before. It seemed like a simple wiki, but personally I would go with Confluence or Mediawiki. I think you may grow frustrated by limitations of the simpler wikis.

  • http://degyes.wordpress.com/ Dave Egyes

    Lots of good stuff in this article.

    I would propose relating to a Wiki less as a tool, and more as a platform for knowledge sharing. The content posted to a Wiki is often dynamic, stemming from the various professionals populating an organization who’ve shared it on a “voluntary” basis. Thus, although the content posted to a Wiki could potentially be highly technical, it is often related to as informal knowledge. Rather than coming from the top-down as formalized and “official” documentation, it tends to emerge from the grassroots.

    For these reasons and others, we find that Wikis work best when someone within the organization (a technical communicator could be an excellent candidate) serves as a catalyst, going out among his/her peers and harvesting and developing knowledge from the community, stimulating conversations to take place, and capturing the knowledge that emerges from those conversations.

    I address this in an a book review that I wrote a short while back as a response to having read Anne Gentle’s Conversation and Community.


    Wikis can serve as a platform for a variety of types of documentation, including Help, though I wouldn’t necessarily have related to Wikis as a Help Authoring Tool (HAT) per-se. HATs tend to be the domain of a few highly skilled practitioners within an organization, who have furthermore been deemed worthy of being granted (rather expensive) licenses for whatever HAT the organization has chosen to implement. While HATs might offer the advantage of enabling generation of a specialized set of Help product targets (WebHelp, HTML Help, .NET and single-sourced outputs) Wikis have the advantage of offering a forum that’s truly democratic in the sense of accessibility across the organization, while being comparatively inexpensive in terms of ramp-up.

    Kudos on a well-presented piece, and for keeping this conversation going!

    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Dave

      I think you’ve hit the nail on the head. There’s all that goodness of the collaboration and sharing side of the wiki. We want to take advantage of that, in our technical documentation, because our primary purpose is to make information available to people, to help them use our products. A great way of making that information available is to give the people a platform where they can help each other.

      The words you used are lovely: a technical communicator would be “going out among his/her peers and harvesting and developing knowledge from the community, stimulating conversations to take place, and capturing the knowledge that emerges from those conversations”.

      On the other hand, we do need tools that we can use to make the information available to people who can’t come to the wiki. Those may be customers who are stuck behind a firewall. They need to be able to download the information on a fairly regular basis, and put it up inside the firewall in some form or other. Or there may be service representatives who spend most of their day out and about. They may need a cut-down version of the docs on their mobile devices or on paper.

      In other words, we’d like the wiki to supply all the things that technical writers need.

      We want to have our chocolate and eat it too. 😉

      Cheers, Sarah

  • http://www.pattyblount.com Patty Blount

    I think you nailed it when you asked “Can we have all the features in one tool?” That was the biggest issue for us when we started researching wiki tools about two years ago.

    Lots to consider here. Thanks for another great post!

    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Patty

      Thanks! Yes, it’s a difficult balancing act, isn’t it! I can’t help wondering how soon we’ll start ranting about the complexity of the tool, if we start adding all the functionality that an authoring tool has. For example, do we need the ability to define semantic elements within the text, such as UI controls and UI labels? On the one hand, that would be excellent because we could then style them at the flip of a CSS switch. On the other hand, it lays the onus on all authors, community or not, to tag their content with the appropriate semantic tags.

      A conundrum indeed. This is why tech comm will never get boring. :) We’re trying to explain a complex world in the simplest way possible, and to allow other people to help us explain it too!


  • Melanie Blank

    In my last job (a long-term contract that ended several months ago), we used MediaWiki to make various internal procedures readily available on the company Wiki(mostly for software developers and technical service people). It worked out well for this purpose.

    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Melanie

      Thanks for commenting. :) MediaWiki is a popular choice. It’s free and open source, which makes the platform a community project in itself. Two of the wiki sites mentioned in this blog post are hosted on MediaWiki platforms: WoWWiki and splunk>docs. You probably know of others too.

      A little bird told me that Tom is a MediaWiki expert too. 😉

      Cheers, Sarah

      • http://idratherbewriting.com Tom Johnson

        I should write a post comparing Mediawiki to Confluence sometime (the problem is that I don’t know Confluence well enough). Mediawiki has several limitations that might make it less appealing to a tech comm group. For example, exporting to print, creating drafts, segmenting projects, defining editing rights — Mediawiki lacks all of these features. But then again, the platform is free, and there are some robust extensions such as the Semantic Mediawiki extension, that are somewhat unique. It scales and is robust. I haven’t used Confluence but keep meaning to try it out. The problem is that once your organization embraces a wiki, it’s difficult to switch. Therefore, if you’re in the planning stage, weigh your options and requirements carefully.

  • http://knowledgecenter.zuora.com/ Neal

    I’ve been using Mindtouch as a HAT and a way to collect and deliver content created by other experts in the company (I’m the only tech writer, so I need all the help that I can get). I haven’t finished making the site look as nice as I’d like to, but it’s a great way to deliver documentation for a web-based product that’s on a monthly release schedule. It certainly makes more sense than generating and delivering huge PDF guides! Plus, I get comments and ratings from customers, and Google Analytics gives me a huge amount of data that I couldn’t get from PDFs.

    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Neal

      I clicked through from the link on your name, and found the knowledge center. Thanks! It’s great to take a look around a doc site created on MindTouch. I liked the “popular topics” feature, and the nice clean structure of the site.

      You make a good point about Google Analytics. We use that too, and it does give some excellent information about how readers are using the documentation. Our team is putting a bit of effort into getting more out of Google Analytics at the moment. There’s quite a science behind it. What’s more, the graphs are pretty!

      It’d be interesting to compare the number of responses you get the different ways of asking for feedback — via comments and ratings.

      Another thing I found interesting is that the site shows all available options in the menus, including actions that I don’t have permission to perform. That’s great for me (and for MindTouch) because I can see all possible functionality of the platform.

      Cheers, Sarah

      • http://idratherbewriting.com Tom Johnson

        It is interesting that Mindtouch doesn’t really emphasize the fact that their platform is based on a wiki. I wonder why that is. Maybe it comes back to my initial question — why aren’t wikis used more? Perhaps companies are hesitant to embrace wikis, but are more than willing to embrace all the functionality wikis bring.

        Neal, if you’d like to write a post about your experience using Mindtouch, get in contact with me. I would be interested to hear about this.

  • http://everypageispageone.com Mark Baker

    Great article, Sarah. I think that the reasons many writers reject wikis is either that they just don’t understand the web, or they don’t want to give up the control they think they have when producing books.

    But one thing you said made me go “Huh!?” out loud. Wiki’s aren’t goog at topic-based authoring? Of course they do! Wiki’s as all about topic based authoring. The problem is, we seem to have lost sight of what topic-based authoring is all about.

    This inspired are rant too long for a comment: http://everypageispageone.com/2012/02/24/frankenbooks-must-die-a-rant/

    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Mark

      I enjoyed your Frankenbooks post. You do know how to stir things up. :)

      Thanks for asking me to think about what I meant by “topic-based authoring”! Good point. My answer is in my reply to Pamela below.

      Cheers, Sarah

      • http://everypageispageone.com Mark Baker

        Hi Sarah,

        I felt a bit bad about making you the occasion (though certainly not the subject) of the Frankenbooks rant. You are one of the most thoughtful people in tech comm, and certainly not someone who is going to fall into the Frankenbook trap, so thanks for being a good sport about it.

        And boy, I must still have had steam coming out of my ears when I wrote my original comment. It’s virtually illiterate, and certainly a grave discredit to my typing teacher!

  • Pamela Clark

    I echo Mark’s question about what you mean when you say that wikis aren’t good at “topic-based authoring”. Just what did you mean by that statement? Wikis are all about topics, yes? They don’t enforce “structured writing” or “structured topics” – is that what you mean?

    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Pamela and Mark

      That’s a really good question: What do I mean by topic-based authoring. Pamela, you’re right. I was thinking of an imposed structure on a page. In DITA and structured authoring, writers create modular chunks of information that can be combined in different ways. One might write a task, and a concept, and a reference topic, then perhaps combine them into a single page or document for one of the output formats.

      In a wiki, people tend to write the conceptual, step-by-step and reference information all on one page. So the word “topic” often has a broader meaning. This is especially true of wikis where the wider community adds information.

      Many wikis do provide functionality that allows content reuse. It’s therefore very possible to define modular topics and reuse them in different areas of the documentation. It’s not so easy to combine a set of topics into one output format, and a different set of topics into another. That’s the conditional publishing side of things, and is one of the benefits of topic-based authoring.

      Thanks for the great question. Mark, I think you’re right that we need to think about what we mean when we say “topic-based authoring”. I don’t think that we’ve lost sight of it. I think the concept is evolving, and we’re not all on the same page. :) These comments have made me think about it all again, and I’ve learned that I need to learn more about it. Thanks!

      Cheers, Sarah

      • http://idratherbewriting.com Tom Johnson

        I know what you mean about the limitations of topic-based authoring on a wiki. When I write in a help authoring tool, I can leave topics really short, like 200 words or less. Length is not an issue. But the nature of wikis calls for longer pages; just having one short topic makes the wiki an endless pile of flat links. Here’s an example page: http://tech.lds.org/wiki/Viewing_calendars. If writing in a HAT, I might break these topics up so they would all be separate topics. Then I could reuse the topics in more flexible ways. But if I broke them up into separate pages on the wiki, it would be a nightmare for users to navigate and find information.

        I don’t know Confluence that well, but Mediawiki allows for content re-use (I bet Confluence does as well). You can create a template of information and then insert the template into topics as needed. The catch is that templates are less intuitive to edit, so they work against the idea of community editing. But templates in Mediawiki are no more confusing that snippets in Flare or other HATs. No matter what tool you’re using, content re-use requires more sophisticated planning and forethought.

  • http://mickdavidsonpicturesword.weebly.com/captains-blog.html mick davidson

    Hello Sarah,
    How are you? Great article, and a good question.
    I’ve been using a wiki for my documentation for three years or so and they are, without doubt, the most exciting thing to happen to tech docs in DECADES.
    Talking to various employment agencies, it’s been made clear to me that many tech writers don’t want to learn new technologies such as wikis because “they’ve been using Adobe (or similar) for decades and are too set in their ways”.
    Personally I find this amazing because I think we all know that if we don’t learn new skills, we’re dead. But if it is true, then it seems that tech writers are part of the reason why wikis aren’t used more.
    Another reason they aren’t is that businesses don’t realise just how powerful a tool wikis are. Wikis are not complicated to use (everything an author needs to know can be learnt in an hour or less) but getting businesses to understand the benefits (extensible, customisable, programmable etc) is a very slow process. I know this from my own experience. The wiki is a magnificent business tool that can do pretty much anything you want it to, but management only see it as a pretty knowledge base.
    On another note, it’s interesting to see how little difference having extensive wiki experience makes to your CV. I’ve been looking at tech writing roles in the UK and elsewhere in the English-speaking world and the thing that’s always missing in the job spec is the word ‘wiki’ (and ‘content’); so either wikis are not being used so widely, or they’re not seen as a valuable business tool.
    Which is very frustrating when you’re trying to find a role in a company that has a wiki and needs your skills. :)
    What I don’t understand is how a company like Atlassian (whose Confluence wiki is far and away the best enterprise level wiki on the planet) are making any money. It can’t all be coming from Jira etc. Some of it has to be from sales of Confluence – but where are the businesses who use it? I can’t find them and most employment agencies that I talk to have no idea who Atlassian are or what a wiki is. How can this be?
    Despite this, I totally believe that wikis are the way forward for tech docs. I would be amazed if wikis are not the dominate tool within the next tens years, perhaps even five. In that time I’d expect to see maybe as much as 50% of all tech writers using them as their No 1 way of presenting their user info etc to clients, and that a similar percentage of businesses will be using them for internal processes.
    PS, Sarah, did you see my photos from my recent trip to Melbourne? http://mickdavidsonpicturesword.weebly.com/melbourne-australia.html

    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Mick!

      It’s great to see you drop by. :) Those are gorgeous photographs. I particularly like the tree trunk.

      Thanks for the additional points about why people aren’t using wikis as much as they could be. I think you’re dead right when you say that people in general don’t know the capabilities of a wiki. In that sense, it’s still a “new” platform even though wikis have been around for 17 years. (The first wiki site was Ward Cunningham’s WikiWikiWeb, in 1995.)

      A strength of wikis is that they’re still under rapid development, and provide platforms for innovative extensions by third-party developers too. I suppose we could see this as a two-edged sword, because it’s hard to keep up with the new features. Maybe when someone investigated last year, the wiki could not do one of the things that person wanted, but now it can.

      Ha ha, I’m sure one of the Atlassian sales or finance team members can explain how the company is making money. 😉

      It’s great “speaking” to you again.

      Cheers, Sarah

      • http://mickdavidsonpicturesword.weebly.com/captains-blog.html mick davidson

        Thanks, Australia makes good photos because it’s a great place and there’s plenty of sunshine. :)

        Wikis… So why am I not seeing more about wikis in the job specs out there? I know Atlassian have 100s of clients world-wide using Confluence, so they are definitely out there. (Perhaps you could send me you client list…)
        I can only dream of the day when employers wake up to power of the wiki and in the meantime I’ll keep rattling their cages.
        Next time I’m in Melbourne (perhaps next January) Atlassian ought to fly myself (and a guest) up to Sydney for a few days. You’ll get excellent client feedback and I’ll treat you to a coffee – sound like a deal? :)

        • http://ffeathers.wordpress.com Sarah Maddox


    • http://idratherbewriting.com Tom Johnson

      “Despite this, I totally believe that wikis are the way forward for tech docs. I would be amazed if wikis are not the dominate tool within the next tens years, perhaps even five. In that time I’d expect to see maybe as much as 50% of all tech writers using them as their No 1 way of presenting their user info etc to clients, and that a similar percentage of businesses will be using them for internal processes.”

      I agree with you 100%. I used to author with a typical help authoring tool. Since switching to wikis, I can’t imagine authoring help content any other way. The whole idea of compiling and publishing help targets (as with HATs) seems so outdated to me. Collaboration, mutual content-ownership, web-based interfaces, ongoing updates — wikis provide so many benefits. The need we once had for the print and web version of the same content is not a need I have anymore. Everything is web.

      • http://mickdavidsonpicturesword.weebly.com/captains-blog.html mick davidson

        Damn that typo! (tens…)

        Thanks for your comments and I’m glad you agree, I do wonder if it’s wishful thinking (definitely in part – brave new world and all that!) but the tool speaks for itself and one day the rest of the docs world will catch up.

        We’re now at the point where not only can clients and staff leave comments but clients can also edit our user info (a big leap of faith) and developers, consultants and others are actually writing additional user info without any prompting for me. Some people are even starting to make it their personal workspace, which means instead of hiding their info on C drives etc, it’s now in the wiki – WHERE IT CAN BE FOUND!

        We’re slowly making developers and supporters watchers of the content they are responsible for creating or supporting. Which is a good thing as when you do this they get emailed automatically and therefore always know what’s being changed, and can get involved in the process if necessary.

        Non-technical staff are beginning to see how it can be useful to them too. For example I showed someone in Personnel how to use the Gliffy plugin to make an Org chart. Now she doesn’t have to create it in Excel, then import it into the wiki (and fiddle around with it so that it is usable), then repeat the process every time someone moves desk. It’s just a matter of editing the chart in the wiki. And now that chart is a template for all the other ones she needs, so the amount of time and effort saved is huge – and the user is very happy with the whole thing.

        So yet another way of saving time and money and making everyone more productive with almost no effort…

        Another thing we’re doing is creating links between our modules and the relevant wiki pages. That way we don’t have to write Help any more, which saves a lot of time and money.

        As far as page length goes, our rule of thumb is to keep the pages as short as possible, preferably all info is shown in the browser without the need to scroll. This isn’t always possible of course but navigating using Page Up/Down makes it easier. We also have some pages that are only one or two lines long, which I’m not really in favour of (because they’re so very small) but sometimes that’s what the content type (e.g, a FAQ) demands. But the advantage is that having a page with one topic makes searching easier because you can search for something specific. If there is more than one topic on a page you have to give it a generic or very long title, neither of which are good for searching on.

        And while we’re on a roll here, searching in Confluence is brilliant and very easy to do, AND everything can be linked, and links are easy to maintain (because you don’t have to do anything about changing them 99% of the time – if a page is moved, then the wiki automatically redirects you – brilliant!)

        Did I mention embedded video?

  • http://meatgrinder101.com Jansen

    I agree Confluence has brilliant search capabilities and is easy for all to use. I however prefer Docu-wiki for a more balanced viewpoint

  • Michael Milliken


    How do you get Development and QA to spend the time to test and verify (or reject) changes and ideas that come into the wiki from customers?

    • http://mickdavidsonpicturesword.weebly.com/captains-blog.html mick davidson

      that’s very easy because I do all the checking! :) I’m the senior admin and am in charge of policing all site activity.

      Also, our wiki is not available to anyone who isn’t either a client or member of staff, so we don’t have the potential for random changes from 100s of 1000s of people.

      Clients don’t tend to change much (at least at the moment) because they way they use our software is different for each client. So the docs are pretty much a vanilla version, with some scenarios, use cases etc added to highlight different ways of doing things. So they don’t change the content much as they know our version has to give the big picture, not just one client’s view.

      However, if I need to query a change with dev, then I send it to the dev team (or the support team) responsible and ask them to double check it.

      At the moment the bulk of the feedback comes from comments about the content of a specific page. This could be a query about how do something we haven’t documented (given the above) or because they need clarification, or they think we could expand the current information. Sometimes they’re telling us the content is out of date. :)

      We try to turn all comments and client changes around within 24 hours. Sometimes it takes longer, but most of the time its resolved well within that time.

      All of which is great!

      • Michael Milliken

        Must be nice. One of the products that I support is a mainframe database management system with many hundreds of customers, each of which has multiple employees working on it, consisting of Fortune 500 corporations, government agencies, and service providers all over the globe. Users range from old timers to newbies. Current set includes 31 manuals covering varing levels of expertise plus online help systems. Any substantive change requires vetting through Development, QA, and Support at the same time that they are creating the next release. We are adding formal scenarios based on use cases. We are also adding a wiki to provide an easier way for customers to comment on their ideas and needs than our current bug reporting system.

        • http://mickdavidsonpicturesword.weebly.com/captains-blog.html mick davidson

          Yes, our system and number of users of any sort is just a percentage of yours, so we benefit from the small scale. We can be more flexible and perhaps more open because we got less to worry about.
          Your system is massive in comparison and the potential problems far greater just because there’s so much to manage. I think policing a wiki that deals with those sorts of numbers means you need to dedicate someone to police it all the time.

    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Michael

      That’s a great question. Mick gave an excellent answer, and his answer also illustrates the point that the experience differs depending on the audience and on the requirements of the organisation.

      Our documentation wiki is open to the world. Anyone can add a comment, even if they do not have a wiki username. Anyone can sign up for a username, if they would like to be identified and to create a personal profile on the wiki.

      If people want to update the pages, rather than just adding comments, then we ask them to sign a contributor licence agreement. That’s an online form, so it’s quite easy to submit. We have around 50 licensed contributors at the moment. The contributors don’t tend to edit the pages much, and when they do it’s always a valuable update. Nevertheless it’s important for the technical writers to monitor all updates, both from within and outside the company. We have a team of technical writers, and each of us is responsible for part of the documentation (one or more products).

      If someone makes a change that we’re not sure about, then we ask a developer or a support engineer for assistance, just as Mick does.

      The support engineers also monitor the comments and provide answers to support-related questions. If someone adds a comment suggesting a new feature or reporting a bug, then we usually ask them to raise the request in the issue tracker. If someone asks a support-related question where the problem is associated with that person’s environment or setup, then we ask them to raise a support request.

      Very often customers answer other customers’ questions. That’s very nice to see!

      The volume of comments coming in to the wiki is too high for a technical writing team to manage without help. That’s why it’s great that people help each other, and that the developers and support engineers chip in when they can.

      Cheers, Sarah

      • http://mickdavidsonpicturesword.weebly.com/captains-blog.html mick davidson

        had me one of those licenses! I want in! :)

        • http://ffeathers.wordpress.com Sarah Maddox

          Hallo Mick

          Do you mean that you’d like to contribute to the documentation? That’d be great. Here’s the info about signing up: http://confluence.atlassian.com/display/ALLDOC/Atlassian+Contributor+License+Agreement

          Cheers, Sarah

          • http://mickdavidsonpicturesword.weebly.com/captains-blog.html mick davidson

            Thanks. I notice the Affected Documentation list doesn’t include Confluence, is that because anyone can edit it, or no one can?
            It’s what I’d be interested in contributing too as it’s what I use. I’ll be using Jira sooner or later, but not every day, so I’m not sure I’ll have much to contribute to that.

          • http://ffeathers.wordpress.com Sarah Maddox

            Hallo Mick

            Thanks for that comment. The Confluence docs are mentioned, but it was not obvious because the space name is DOC rather than anything that makes you think of the wiki. This odd name is due to an accident with a key and a time machine. 😉

            I’ve highlighted the names of the major products in bold on that page, so that the Confluence docs are more obvious.

            Cheers, Sarah

  • http://www.describewriting.com Maeve


    In fact, Atlassian should pay me commission for prosthelytizing Confluence to every new client I work with. Once you go Confluence, you never go back. With Confluence, my time is spent on the message, not fiddling with a buggy application.

    I agree with the individual who suggested we give it a year because the landscape is changing re: wiki use. With everything moving to the cloud, if doc tools don’t follow, they will be left in the dust. How antiquated is it to open a desktop application now? Imagine what a dinosaur it’ll feel like a year from now.

    I would say to start small and (possibly with guidance from Confluence experts at Atlassian) have a roll-out plan that introduces collaboration over time. I also recommend using a plug-in called Adhoc Workflows to manage your documentation workflow. Handy add-on to manage approval stages.

    Sarah, I know your dev team is busy working daily on a million improvements to Confluence, but I hope one day to see the free-form capabilities of InDesign integrated into the wiki. I believe you guys can do it.



    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Maeve

      Wow, thanks for all the good words about Confluence. :) I’m very interested in these words of yours: “I hope one day to see the free-form capabilities of InDesign integrated into the wiki.” Would you expand a bit on what those capabilities are?

      I don’t know if it’s related, but there’s a plugin that you may find interesting: The “Scroll Wiki Forms” plugin by K15t Software. It’s still an early-adoption release, not ready for production use. The team at K15t are keen to receive feedback on it:

      Cheers, Sarah

      • http://www.describewriting.com Maeve

        Hi Sarah,

        InDesign is a desktop publisher that lets you design page layouts. For a simple example, I can place an image anywhere on the page and wrap text around it.

        Here’s a link to the InDesign page that shows you how magical it is: http://www.adobe.com/products/indesign.html

        InDesign + Confluence = Ultimate Documentation Tool (for me at least).



  • http://ffeathers.wordpress.com Sarah Maddox

    Hallo all

    Someone asked me offline about plugins, and specifically about workflow, single sourcing and version control. I’ll paste my reply here, because it may be useful to other people too.

    Most wikis support extensions, sometimes called add-ons or extensions. Confluence is the wiki I know best, so I can point you at the core functionality and the plugins for Confluence. The documentation for the other wikis (such as MediaWiki) should give you some pointers too.

    For Confluence, you can do a simple workflow (draft, review and publish) without installing any plugins. The documentation include guidelines on this basic usage, plus links to the plugins that provide a more sophisticated workflow:

    For single-sourcing, you can publish to PDF and HTML using core Confluence functionality. There’s also a basic Word export, but that works only at page level. Plugins provide enhanced Word and PDF export, plus export to DocBook, DITA, and other formats. This blog post has the details:

    This post has more up-to-date information about the DocBook exporter:

    Regarding version control: The page on workflow, mentioned earlier, has the details of the Ad Hoc Workflow plugin. In addition, a new plugin is under development by K15t Software, but it’s still in early phases of alpha testing. If you’re interested, I’m sure the team at K15t Software would love to hear from you:

    K15t Software are also developing the Scroll Wiki Forms plugin, which will allow you to protect the formatting of your content elements. That plugin is also in the early stages of development, and I’m sure they’d love to have your input.

    To search for information about plugins, try the Atlassian Plugin Exchange:

    For example, this search finds all plugins that provide forms on top of the wiki content:


  • http://mickdavidsonpicturesword.weebly.com/captains-blog.html mick davidson

    Thanks, I’ll sign up right away. :)

    • http://mickdavidsonpicturesword.weebly.com/captains-blog.html mick davidson

      @Sarah – done! :)

  • http://www.atlassian.com/software/confluence Matt Hodges

    For those interested, Sarah published her first post in a series of blogs about using a wiki for technical documentation, today – A Day in the Life of Technical Writer – http://blogs.atlassian.com/2012/03/a-day-in-the-life-of-a-technical-writer/

  • Ravikumar Babu

    Perfect timing, Sarah!

    Just this week I started using Confluence for a new assignment and today I found this article with good discussions about wiki!

    Even though wikis have their drawbacks, I am excited in using them. It’s been a welcome break for me from more than a decade of writing documents in traditional tools.

    • http://ffeathers.wordpress.com Sarah Maddox

      Hallo Ravikumar

      It’s great to hear you have the opportunity to use a wiki. I remember the pleasure, and the lightness of being, that I felt when I first moved onto one. It’s a great experience that just keeps getting better as I gain more knowledge and understanding of the tool, and as the wiki grows in functionality too. There are challenges and frustrations of course, but every tool has those to offer.

      Have fun on your wiki. :)

      Cheers, Sarah

  • Pingback: Frankenbooks Must Die: A Rant | Every Page is Page One()