Should we allow comments on documentation pages

This is a very interesting question: Should we, as technical writers, allow comments on our documentation pages? It’s interesting because it’s a multi-faceted question, and because people have such strong feelings about it. My quick answer is, “Yes”. Ha ha, but there’s always a “but” or two. Read on, and then I’d love to know what you think.

I’m a technical writer at a company called Atlassian. We write all our product documentation on a wiki. For example, here is the Confluence user’s guide. What’s more, we have configured the wiki permissions to allow anyone to add comments to the pages. (We also allow known contributors to update the pages – but that’s another story.) Every now and then, the question comes up for debate again: Is it a good thing to allow comments on the pages? Up to now, we have decided each time to keep the comments. (Well, except for the developer documentation. More below.)

Multi-faceted question

We could rephrase the question like this:

Should we ask for feedback on the documentation? If so, are comments the best way of getting that feedback?

Or like this:

Should we allow everyone to comment on the documentation, or just known people?

Or:

What benefits do our customers get from being able to add and read comments on the documentation?

Or:

What benefits do we, as technical writers, get from the comments people add? And do we suffer any pain?

Mmmm…

What  benefits does the organization get from allowing people to add comments to the documentation?

And so on.

Examples of comments

On the Atlassian product documentation, we allow everyone to add comments. Even people who have not logged in to the wiki – their comments  are recorded as “anonymous”.

Some comments are very relevant to the documentation itself. For example, the comments on this page about supported platforms in the Confluence administrator’s guide:

Some of the comments on the supported platforms page

Other comments can be requests for help, or suggestions for new features or improvements in the product. Often a reader will add some information that will be useful to other readers. This one is on the page about configuring Tomcat’s URI encoding:

A reader offers information to others

Advantages of allowing comments

A quick list:

• People tell us about errors or gaps in the documentation.
• People use the documentation as a tool to help each other.
• We learn about new ways that people are using our products, and sometimes even about new ways that they want to use the documentation.
• The documentation becomes an active hub of interesting information. Readers receive notifications when other people add comments, and so keep coming back to the documentation to see the latest. The documentation sticks in their minds as a good place to find what they need.

Disadvantages of allowing comments

Another quick list:

• Comments can make a page hard to read, if there are too many of them.
• People may add worthless comments, spam, or even nuisance comments.
• It is time-consuming, if not impossible, to respond to all the comments.
• It is time-consuming, if not impossible, to clean up the comments when they are no longer needed. (But we could automate this.)

Please add a comment 😉 to this blog post, telling me what I’ve missed in these two lists.

No more comments on the developer documentation

A few months ago, we moved all of the developer documentation to a different wiki, the Atlassian Developers site. By “developer documentation”, I mean the API reference guides, the plugin development tutorials, and all the stuff related to developing add-ons and extensions for our products.

The developer documentation is still on a wiki. In fact, it’s a Confluence wiki just like the product documentation. But we have customised the look and feel, and added some plugins. The thing to note, from the point of view of this post, is that we have turned off the page comments. Instead, there are two panels at the bottom of each page:

Atlassian Answers and feedback panels

The “Atlassian Answers” panel shows a list of posts drawn from a discussion forum called Atlassian Answers. The panel is supplied by a plugin for the wiki that hosts the documentation. The plugin matches the labels on the documentation pages to the tags on the discussion forum. The matching process is not perfect. In particular, labels and tags are not the most reliable way of matching content from a discussion forum and a documentation site. We plan to improve this, by a smarter matching of page titles and content.

The “feedback” panel is supplied by another plugin. When a person clicks “Yes”, “Somewhat” or “No”, a dialog appears where they can give us more information. The plugin posts an email containing that feedback, which in turn triggers the creation of an issue on our JIRA issue tracker. The technical writers and developer relations team can then assess and react to the feedback.

Comparing comments and feedback forms

An advantage of comments over feedback forms is that readers can see and respond to each other’s comments. People can benefit from the advice of other readers. They can hold a conversation and help each other solve problems, quite independently of the documentation authors.

Comparing comments and discussion forums

An advantage that comments have over discussion forums is that the comments are right there on the relevant page. People do not need to go looking for them on a separate discussion site. The information in the comments complements what is on the page.

On the other hand, a discussion forum is in itself a repository of information. I guess, as a technical writer, I’d like to keep people’s attention on the documentation. I’d prefer it if the docs did not become a dead site, for reference only.

But what serves the customer better?

What do you think?

Heh heh, it’s a complex question. And now let me add this specific question to the list: Would you cry if we removed the ability to comment on the Atlassian documentation in particular? (This is just a general question. There are no definite plans at the moment to remove commenting.)

Let the comments begin. 🙂

WritersUA 2011 – Using social media to get readers involved

This week I attended the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. On Tuesday it was my turn to present a session, called “Getting your readers involved in the documentation”. This post summarises my talk and offers you the opportunity to download the presentation in PDF form.

At Atlassian, we’ve been using social media in various ways, to make our documentation a living, interactive hub where people can find the answers to their questions, talk to us, talk to each other, and use the documentation as a tool to help each other.

Download the presentation

If you like, you can download a copy of my presentation in PDF form. I’ve put a lot of information and references into the speaker’s notes too.

• Download the slides in PDF form (1,642 KB): Getting your Readers Involved in the Documentation (slides only)
• Download the slides with notes in PDF form (1,196 KB): Getting your Readers Involved in the Documentation (slides with notes)

What’s in this post

The rest of this post is a summary of and discussion of my presentation, and of the condensed version that I showed people at the WritersUA peer showcase.

The social organisation

We know that organisations are becoming more social. Studies show that engaged customers buy more, are more likely to be satisfied with the product, and are more likely to help each other use the product.

In the same way, I’d like to propose that engaged readers will keep coming back to the documentation, are more likely to be happy with the documentation, and will use the docs as a tool to help each other.

The tools

The tools and ideas I discussed are:

• Using a wiki as the documentation authoring and publishing tool – Confluence. In our documentation and in my presentation I’m using Confluence wiki. But most of the tools and ideas are transferable to online documentation on any platform.
  • Allowing readers to add comments to the documentation pages.
  • Allowing various groups of people to edit your documentation, including community authors, all the company staff, customers, the whole wide world.
  • Using wiki permissions to determine who can do what.
  • Monitoring the updates via RSS feeds and wiki watches.
• Designing a contributor licence agreement, based on the Apache Contributor License Agreement, to protect the rights of all parties.
• Adding a Creative Commons copyright licence to the documentation pages. Ours is a Creative Commons by Attribution licence, which means that anyone can use the documentation for any purpose they like, provided they acknowledge us as the source.
• Using a web service that allows you to design an online feedback form, then grab the HTML to embed the form into your own documentation page – Wufoo. When people fill in information on your form, the data goes into the Wufoo database. You can then log in to Wufoo and see the results, get some statistics, and so on.
• Linking to blog posts written by community developers and authors from within your documentation. For example, the JIRA Tips of the Trade, the Crowd Tips of the Trade and the Confluence Tips of the Trade.
• Encouraging people to interact with your documentation via Twitter (Twitter.com).
  • Using Twitter as a medium for your release notes.
  • Encouraging people to tweet hints and tips about your products, and then taking it a step further and embedding a live stream of tweets on a documentation page. See the JIRA Tips via Twitter and the Confluence Tips via Twitter pages.
• Rewarding contributors by giving them an online badge that they can add to their blogs or other social sites.
• Organising a doc sprint. This is an event, similar to the book sprints of the opensource world, where a group of people get together for a specific period of time to write a specific set of documentation. We have held two doc sprints, with participants working in our offices and remotely all over the world. We plan to hold more.
• Bringing back fond memories of a documentation-related event, and encouraging people to join in next time, by streaming photos of the event onto your documentation page directly from Flickr. Flickr is a web service where you can upload and share photographs with your community, friends and the world.
• Building fun, a game, a challenge and interactivity into your documentation. I demonstrated at the Dragon Slayer documentation.

The Dragon Slayer Documentation

The Dragon Slayer documentation is a set of installation instructions that we created to solve a specific problem. Atlassian, the company I work for, has a great set of products that you can set up to work together as an integrated development suite. At the moment, though, the integration process is long and complex. In fact, it’s painful. The products were not originally created to work together, and we’re developing the integration incrementally. The setup process is getting easier all the time, because our developers are working to improve the process.

In the meantime, we needed some documentation that leads people through the setup process, to create a specific environment with some good simple examples of the integration possibilities. This documentation does not replace the existing installation and upgrade guides for each product. Instead, it’s an additional tool to get people started quickly when they want to set up the full suite of products.

What’s more, because the process is long and complex, we wanted to turn the pain into fun. So we challenge people to come a slay the dragon. The dragon is, of course, the setup process.

A summary of the Dragon Slayer docs:

• There are 9 stages, corresponding to 9 pages. Each stage consists of many steps.
• We’ve taken pains sure ensure that the fun stuff is at the top and bottom of the pages. In between is good, solid technical writing – “how to” steps that we test rigorously, end-to-end, before making any updates, to ensure that the entire environment will work.
• There’s a pretty picture and some funny words (shamelessly cribbed from various online translations of Dante) at the top of each page.
• At the bottom of each page, we congratulate you on your victory and tell you what you have achieved so far.
• When you start out on the dragon quest, you meet Sir Charlie of Atlassian, whom you will recognise as the dude in the Atlassian logo. He is scantily clad and has only a staff to ward off the dragon.
• As you go through the stages, Charlie acquires armour and a sword, so that he is well equipped by the time he meets the dragon in stage 9.
• When you finish the dragon quest, you get a T-shirt. (A real one.)
• During the quest, you can intereact with other dragon slayers via Twitter. We’ve crafted some funny tweets that are a call to action. If you click the “Tweet” link, we prepopulate your tweet box with those words. You can delete or change them before tweeting. We also embed a live stream of tweets on the Dragon Slayer front page, so that people can see which dragon slayers are out there right now.
• Each page also has a number of links to the dragon slayers’ forum, where you can discuss any problems you encounter and swap ideas with other people going through the procedures at the same time as you.

The plan is that the Dragon Slayer documentation will morph into a set of quick, simple steps. The dragon may disappear entirely. Or maybe not. Watch this space. 😉

The WritersUA peer showcase

I presented a condensed version of the presentation at the WritersUA peer showcase on the last day of the conference. What happens at the peer showcase is that you sit at a table for two hours, and people drop by in groups or individually to see your project. So you need just a short demonstration. I focused on our use of Twitter in and around the documentation, and specifically on the Dragon Slayer documentation.

I was completely overjoyed when I won the award for the most innovative peer showcase project at the 2011 Conference for Software UA. Thank you so much to everyone who voted for our project, and to Atlassian for giving the technical writers the opportunity to do such fun stuff in our documentation.

Bye

I hope you find the attached presentation useful. Let me know what you think, and if you’re doing something similar.

WritersUA 2011 Monday – Hotrodding your online help

This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. These are my notes from the session called “Hotrod My Help” presented by Leah Guren. If you find any inaccuracies, they’ll be mine.

Leah’s presentation style is both informal and professional. She started out by introducing herself as “this deranged woman”. She then became more serious quite quickly. Her talk was about design of online help systems. She used the metaphor of hot rodding – talking about the paint rather than what’s underneath.

Introducing the topic

Leah’s talk was entirely tool agnostic, and described techniques that we can apply to our documents with very little effort.

Nevertheless, Leah pointed out, this stuff matters for a number of reasons:

• Design should match the subject matter.
• Better design improves usability.
• We’re not talking about making things look pretty. We want to make sure that what we develop will communicate as effectively to users as the words we choose.
• When people see help with a sloppy design, they’re less likely to trust the information.
• Design should support the meaning of the content.
• It should make it easier for people to find what they’re looking for, to recognise it and to use it.

Leah also pointed out that if your readers are noticing the design, then you have made a mistake. (As a side note, I tweeted this point and received an interesting reply from Bill Kerschbaum.)

The design concepts

Leah introduced us to some design concepts, the jargon. Mastering the terminology lets you defend you choices with more authority.

Leah introduced us to the acronym PARCH:

• Proximity – When elements are close together, we recognise that they are related.
• Alignment – Choose where you position elements on the screen, to develop a meaningful design.
• Repetition – Repeated visual patterns help people to access and remember the information efficiently.
• Contrast
• Hierarchies and dependencies

Proximity

One stylistic mistake that violates this principle is the “floating heading”. That’s when you have a heading with the same amount of space above it as below it. Instead, there should be less space below the heading, to bring it closer with the content it describes.

Alignment

Use alignment for a less sloppy design.

Repetition

Consider things like colours, icons, placement.  Stylistic repetition reinforces the information for the user and gives them more confidence.

Contrast

We need contrast so that people can see the differences in meaning between different elements on the page. For example, links should look different from other text. So should headings, and layered information. The rule of contrast is that it must be meaningful. Readers don’t care how you do it, whether you use a list or headings or bold text. Just be consistent and make it meaningful.

Hierarchy

This defines how elements of information on the page are related to other elements on the page. Consider the use of white space and indentation.

Other concepts and techniques

• White space – Consider margins, space between lines, hanging indents, paragraphs etc. White space is critical. If you don’t have enough white space, the text is not readable. Users flee from densely-packed screens.
• Plumb lines – Draw vertical lines at every point where an information element starts, to make a clean design. Good clean design steps into the background. Bad design is noisy.
• Indents and text wrap – Indents help the concept of contrast. Good examples are bulleted lists.
• Paragraphs – Leah recommends the following design techniques for paragraphs, to enhance readability:
  • Flush left, ragged right.
  • Single line spacing.
  • White space between paragraphs.
• Chunking – Use white space intelligently, to show the logical visual chunks of information.
• Nesting – Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting. The rule in technical communication (a tacit contract with the user) is this: if I’m going to break the information down into logical categories, there must be more than one category. For example, you can’t have just one item in a bulleted list, or just one level-2 heading.

Examples – applying the concepts

After introducing all the theory, Leah moved on to examples of web page makeovers, using her hotrod metaphor. She took us through some real documentation and web pages from various sites, and applied her principles to each one.

These are some of the mistakes she fixed up:

• Messy text.
• Dashboard that was not designed to be meaningful.
• Screenshots taken without care and without tidying up afterwards.
• Sloppy text wrap, that probably happened when pasting content from elsewhere.
• Inconsistency in capitalisation, punctuation, and so on.
• Long lines that force the user to do horizontal scrolling. A typical culprit here is information in tables. This is easy to fix, but easy to overlook.
• No visual cue that content continues below the fold. Readers may think they have reached the end of the steps, without realising they need to scroll down. One way to fix this is to include a “Start” and “End” icon.
• Help window opening on top of the application by default. The solution is to make the default opening position at top right, for example.
• Concordance (repetition of same words) in the table of contents (toc). This is very distracting. If the toc entries are very long, people will not see the meaningful bit in the toc window.
• Use of blue (usually used to denote hyperlinks) as an emphasis or point colour.
• Too many layers of hierarchy (too much nesting) in a table of contents.
• Links in the text. Don’t put links in the text unless they’re popups or dynamic HTML. Keep all links off to the side or at the bottom. People get distracted by links, or click them and get lost.
• Empty topics.

Help authoring tools

If the problem we’re addressing lies within a tool that we use to develop help systems, then the HAT and DITA tool developers need to fix it. We need to be involved in the design of such tools.

My conclusions

Throughout the presentation, Leah had “bonus rounds” where she asked us to name concepts that the pages were violating. She promised us “valuable prizes” (said with a grin) which we could collect afterwards. This was great for getting audience participation going.

Thank you for a lively session, Leah!

Hotrod My Help
=============
Leah Guren (Cow TC) 

http://www.cowtc.com/

Leah started out by introducing herself as “this deranged woman”. Herpresentation style is informal and easy. She then got more serious quite quickly. She does many presentations about tehcnical communication. Today she will talk a lot about deisng. Use the metaphor of hot rodding – talking about the paint rather than what’s underneath.

Everything she will talk about is tool agnostic. These are techniques that you can apply to your documents with very little effort.

This stuff matters because the design should match the sujbect matter. Better design improves usability. we’re not talking about making things look pretty. We want to make sure that what we develop will communicate as effectively to users as the words we choose.

When people see help with a sloppy design, they’re less likely to trust the information.

If your readers are noticing the design, then you have made a mistake.

Good design follows a series of rules.
Design should support the meaning of the content.
It should make it easier for people to find what they’re looking for, to recognise it and to use it.

Leah introduced us to some design concepts – the jargon. Mastering the terminology lets you defend you choices with more authority.

Leah introduced us to a new acronym: PARCH:
* Proximity – When things are close together, we recognise that they are related.
* Alignment – Choose intential places to position elements on the screen, to develop a meaningful design.
* Repetition — Repeated visual patterns help people to access and remember the information efficiently.
* Contrast
* Hierarchies and dependencies

Proximity:
==========
One stylistic mistake that violates this principle is the “floating heading”. That’s when you have a heading with the same amount of space above it as below it. Instead, there should be less space below the heading, to bring it closer with the content it describes.

Alignment
=========
Less sloppy design.

Repetition
==========
Consider things like colours, icons, placement.

Stylistic repetition reinforces the information for the user and gives them more confidence.

Contrast
========
We need contrast so that people can see the differences. For example, links should look different from other text. So should headings, and layered information. The rule of contrast is that it must be meaningful. Readers don’t care how you do it, whether you use a list or headings or bold text. Just be consistent and make it meaningful.

Hierarchy
===========
This defines how elements of information on the page are related to other elements on the page. Consider the use of white space and indentation.

Other concepts:
==============
* White space — Consider margins, space between lines, hanging indents, paragraphs etc. White space is critical. If you don’t have enough white space, the text is not readable. Users flee from densely-packed screens.

* Plumb lines — Draw vertical lines at every point where an information element starts, to make a clean design. Good clean design steps into the background. Bad design is noisy.

* Indents and text wrap — Indents help the concept of contrast. Good examples are bulleted lists.

* Paragraphs — Leah recommends the following design techniques for paragraphs, to enhance readability:
** Flush left, ragged right.
** Single line spacing.
** White space between paragraphs.

* Chunking — Use white space intelligently, show that we’re showing logical visual chunks of information.

* Nesting — Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting, which all of us do. The rule in technical communication (a tacit contract with the user): if I’m going to break the information down into logical categories, there must be more than one category. For example, you can’t have just one item in a bulleted list, or just one level-2 heading.

Examples – applying the concepts
========

With the theory out of the way, Leah moved on to examples of makeovers, using her hotrod metaphor. She took us through some real documentation and web pages from various sites, and applied her principles to each one.

Some of the mistakes she fixed up were:
* Messy text.
* Dashboard that was not designed to be meaningful.
* Screenshots taken without care and without tidying up afterwards.
* Sloppy text wrap, that probably happened when pasting content from elsewhere.
* Inconsistency in capitalisation, punctuation, and so on.
* Long lines that force the user to do horizontal scrolling. A typical culprit here is information in tables. This is easy to fix, but easy to overlook.
* No visual cue that content continues below the fold. Readers may think they have reached the end of the steps, without realising they need to scroll down. One way to fix this is to include a “Start” and “End” icon.
* Help window opening on top of the application by default. The solution is to make the default opening position at top right, for example.
* Concordance (repetition of same words) in the table of contents (toc). This is very distracting. If the toc entries are very long, people will not see the meaningful bit in the toc window.
* Use of blue (link colour) as a highlight colour.
* Too many layers of hierarchy (too much nesting) in a table of contents.
* Links in the text. Don’t put links in the text unless they’re popups or dynamic HTML. Keep all links off to the side or at the bottom. People get distracted by links, or click them and get lost.
* Empty topics.

Help authoring tools
====================

If the problem lies within a tool that we use to develop help systems, then the HAT and DITA tool developers need to fix it. We need to be involved in the design of such tools.

My conclusions
==============

Throughout the presentation, Leah had “bonus rounds” where she asked us to name concepts that the pages were violating. She promised us “valuable prizes” (said with a grin) which we could collect afterwards. This was great for getting audience participation going.

Thank you for a lively session, Leah!

Experiences with readers’ comments on the Atlassian documentation wiki

People are what matters in the documentation world. The docs are for the people and increasingly by the people too. One way of giving people a chance to contribute to, and help each other via, the documentation is by allowing them to comment publicly on the doc pages. Susan Grodsky asked me to write something about Atlassian’s experiences with comments on our documentation wiki. Here goes.

There’s a lot to talk about: setting the permissions that determine who can add comments to the pages, managing those comments, the sort of comments people make, how many comments we receive, and above all, is it a good thing or a bad thing to allow public comments on the documentation?

I’ve done some analysis of the comments we received over a week, from 7th to 14th January 2011. This may be a fairly quiet time of year, but it happened to be the period when I had time to do the analysis.

A bit about our documentation wiki

We write and publish all our documentation on a single Confluence site: confluence.atlassian.com, fondly known as CAC. It hosts the documentation for all our products: JIRA, Confluence, Crowd, FishEye, Crucible, Bamboo, JIRA Studio and more.

Each product has its own documentation “space”. Most products in fact have a number of spaces, one for each major release of the product. Many products also have a separate space devoted to developer documentation – APIs, plugin frameworks and the like. If you go to the CAC dashboard and scroll down, you’ll see the list of spaces on the left-hand side of the screen.

And yes, the documentation for the Confluence product is hosted on Confluence itself. The Confluence documentation space is just one of the spaces on CAC.

Stats of visitors to the documentation wiki in a week

To give some context to the number of comments received, I looked at the traffic that the documentation site received in the week of 7th to 14th January 2011.

Across the entire wiki:

• 99 329 people visited the site, in a total of 157 312 visits.
• 45 549 pages were viewed a total of 540 488 times.
• Number of comments on all spaces: 98

Confluence documentation (DOC space) only:

• 1 793 pages were viewed a total of 99 310 times.
• Number of unique page views: 78 037
• Number of comments on this space: 39

My previous blog post has some pretty pictures and more information from Google Analytics.

Analysis of comments on one documentation space in a week

Here are the results of my analysis of the comments received in the week of 7th to 14th January 2011 on the Confluence documentation (DOC space) only.

• Number of comments on the DOC space in that week: 39
• Who made the comments:
  • 18 comments were anonymous – added by someone who was not logged in to the wiki.
  • 21 comments were from logged-in users.
• What the comments were about:
  • Offering information, hints and tips: 9
  • Suggesting an addition/correction to the documentation: 2
  • An unhelpful comment, possibly meant to be humorous: 1
  • Requesting help on functionality (“how do I…” or “is it possible to…”): 9
  • Requesting support (when something does not work as expected): 13
  • Suggesting a feature or improvement in the product: 5

How I tracked the comments

Google Analytics does not show statistics specifically for comments. Instead, I used an RSS feed generated by Confluence to retrieve the comments over the time period I wanted. (To define the RSS feed you want from a Confluence site, click “Feed Builder” on the Confluence dashboard.)

Permissions and public signup

How do we determine who can add a comment? Confluence has a useful permissions scheme. You can grant permissions to specific users, to groups of users, and to “anonymous” users, the last being people who have not logged in.

Each space has its own set of permissions. The permissions determine what people can do with pages, with blog posts, with space administration, and of course with comments. For example, you might choose to allow only a specific group to add and update pages in a given space. That group might be the technical writers, or the company employees. In another space, you might allow everyone to add and update pages, but only a given group to delete pages, and so on.

Talking specifically about comments: For the Atlassian documentation spaces, we have set the permissions to allow everyone to add a comment. Even anonymous users can add comments. Only Atlassian staff members can remove comments.

We have also enabled public signup on the wiki. That means that anyone can sign up for a username and then log in, immediately and at any time. Once logged in, they’re not “anonymous” users any more. They need to enter an email address, but basically they can use any name, username and email address they like.

How we handle the comments

At Atlassian, each technical writer is responsible for a specific set of documentation spaces. We keep a close eye on what’s happening in the documentation, including any comments added to the pages. There are two ways we do that:

• Select the “watch” option on the space. When you are watching a space, Confluence sends you an email notification of all updates in the space, including comments.
• Use an RSS feed, configured to show all activity over a given period of time.
  

As you can see from my analysis above, many of the comments are from people asking for help rather than making suggestions about the documentation itself. The Atlassian Support team monitors the documentation spaces too. The support engineers are really great at responding to comments. We could not do it all without them.

What’s more, readers often help each other. To me, this is one of the most rewarding aspects of allowing public comments.

The technical writers jump in to answer the comments that relate to the documentation. We answer the comment, update the page if necessary and thank the person for their input. A week later we remove the comment and our reply.

Well, that’s the plan anyway 🙂

In practice, we often don’t have time to respond to all the comments appropriately. We also don’t have time to go back a while later and remove all the comments that the support team and other customers have answered.

The result is that many of our documentation pages, especially in the older spaces, have long strings of comments attached.

We’re considering writing a script that we can run regularly to delete comments that are over two years old (or whatever period we choose). The principle is that the page will have been updated a few times and most comments will be irrelevant after such a long period.

If we do start using such a script, we will write up our comments policy so that wiki users know their comments will disappear eventually, even if we haven’t explicitly replied to every comment.

Are people nasty?

We don’t often see malicious comments. There is of course the occasional frustrated person who can’t get something working. We usually ask them to raise a support request or report a bug on the issue tracker, because the documentation is not the place for venting frustration or for getting immediate help with an urgent problem.

What about spam?

Confluence has Captcha for spam prevention. We have configured it to spring into action whenever an anonymous user adds a comment. Captcha prompts the user to read some text from an image and type it into a form. This is very effective in preventing spambots.

We do get the occasional spam comment from real people – often someone trying to sell watches, funnily enough.  They add their advertisements to the pages about wiki notifications and watches. 🙂

We remove spam comments as soon as we spot them.

Some examples of comments

Here are some of the comments we have received. They’re not all from the week of 7th to 14th January 2011. Instead, I had a look around to find some interesting and representative comments all over the wiki. Most are from the DOC space, though the last one is from the CROWD space.

Some people use the comments just to try out the wiki functionality:

Experimenting with wiki comments

Others get a bit more adventurous, and check to see if they can code JavaScript into a comment:

Trying out a bit of JavaScript

People share macros they have written to extend the wiki functionality. This comment was on a page about the {include} macro. Someone has written a related macro:

Sharing a macro

People do tell us off when something goes wrong. This comment was on the page about backing up and restoring a Confluence site:

Telling us off when something goes wrong

Other people jump to our defence. Below is a continuation of the comment above, and a reply from someone else. The reply is the comment that I counted as “unhelpful, possibly meant to be humorous” in my analysis above:

Jumping to our defence

I stepped in to smooth the troubled waters:

Smoothing troubled waters

Here’s a helpful comment about the documentation itself. Someone who shall remain nameless 😉 had forgotten that we’re not in 2010 any more. This comment was on the release notes:

Pointing out a typo in the docs

Next is possibly my favourite string of comments, because it’s so cute and funny and totally off topic. The comments are still on the page:

Been there, done that, got the T-shirt

Readers help each other. To me, that’s the most beneficial aspect of allowing public comments:

Helping each other

A good or a bad thing?

Receiving and responding to comments keeps the documentation alive, dynamic, iterative, constantly improving. The best of agile.

It’s also chaotic, time consuming and open to occasional abuse.

From looking at the comments themselves, I’d say our customers appreciate being able to have their say, ask questions and help each other.

Me? I love it. I would find it hard to go back to a form of technical writing where there’s less contact with the readers. But I do wish I had more time to give due attention to the comments we receive.

Thank you to everyone who comments on and contributes to the wiki documentation. You are stars!

Social media in technical documentation – a presentation

Last week I attended Atlassian Summit 2010. This was a conference in San Francisco focusing on Atlassian products such as Confluence wiki, JIRA issue tracker and more. At Summit, I presented a session on using social media in technical documentation. We also got a bit emotional about the docs. 😉

This was pretty cool. It’s the first time I’ve given a talk at an Atlassian conference. I was totally stoked and very nervous. Apart from a technical glitch or two (basically, Twitter was borked and my presentation was supposed to use Twitter) all went well. The audience was great. Thank you guys!

Downloading the presentation and watching the video

If you like, you can watch the video of me doing the talk (yes, they filmed me!) or download the slides:

• Watch the video of me giving the presentation on the Atlassian Summit 2010 site. You’ll see two big picture boxes in the right-hand half of the screen. The top one is the video. The first 22 minutes are my part of the session. In the second half of the video, Jeremy Largman talks about using Confluence as a support knowledge base and the tools the support team have built to extend Confluence. His presentation is awesome and packed with information. Well worth a watch. If you’d like to bump up our ratings, click the “Like” button just above the video. Let me know what you think of it too. I’m quite pleased with the way it turned out. I was expecting far worse! I was quite nervous, and my mouth got very dry. They’ve done a really great job of compiling the video with me and the presentation slides in one single view.
• See the slides on Slideshare: Felt the earth move when I read your docs (Slideshare)
• Download the slides in PDF form (1,901 KB) from this blog post that you’re reading now: Felt the earth move when I read your docs (slides only)
• Download the slides with notes in PDF form (1,907 KB) from this blog post: Felt the earth move when I read your docs (slides with notes)

Summary of the presentation

My talk was called “Felt the earth move when I read your docs“. Actually, it was originally called “Felt the earth move when I read your docs, mate” but someone with a fair bit of influence 😉 suggested that I remove the word “mate” from the title. You may notice that the word sneaked into the presentation itself anyway! Here’s a still image that I grabbed from the video:

Social media in technical documentation - a presentation

It’s all about using social media to engage readers in the documentation. It’s also about fun and games and a bit of emotion in the docs. We looked at these tools:

• Confluence wiki
• Twitter
• Flickr
• Wufoo

And we saw how we can use them in technical documentation:

• Using comments and forms to get actionable feedback from readers and customers.
• Linking to external blogs from within the documentation.
• How you can set up and manage your documentation while allowing external people to edit it.
• Using Twitter as a medium for release notes.
• Encouraging customers and readers to tweet hints and tips, and publishing the Twitter stream in your documentation.
• Holding a doc sprint.

To round it off, we looked at the Atlassian Dragon Slayer documentation, which combines a game, social interaction and a laugh with good solid well-tested technical writing.

More

The Atlassian Summit presentation is related to one I gave at AODC recently. If you’re interested in a lot more detail about each of the topics covered here, then take a look at my earlier post: AODC 2010 day 2: Engaging your readers in the documentation.

Craig Smith snapped a cool picture of me giving the presentation. He also wrote some great summaries in his Atlassian Summit 2010 Day 1 Wrapup.  Thanks Craig!

At the end of my slides are a number of references and links that I hope you’ll find useful. They include links to blog posts by other technical writers who are experimenting with social media and other adventures in the docs.

The Atlassian web site has a lot more Summit presentations, including a number about Confluence and how people are using it.

Attending this conference was a great experience. I’m really lucky to have had the chance to be there and to meet all those great people. Thank you to all the attendees for the ideas you brought and the fun we had.