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.)
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?
What benefits do our customers get from being able to add and read comments on the documentation?
What benefits do we, as technical writers, get from the comments people add? And do we suffer any pain?
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:
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:
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:
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. 🙂
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.
- Hierarchies and dependencies
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.
Use alignment for a less sloppy design.
Consider things like colours, icons, placement. Stylistic repetition reinforces the information for the user and gives them more confidence.
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.
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.
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!