WritersUA - Training and Information for User Assistance Professionals

Putting the User in User Assistance

By Anne Gentle

Bookmark and Share


Click a link below to jump to a particular section; click any "CONTENTS" image following a section heading to jump back here.

Introduction    Link to contents

People on today's social web are accustomed to participating in conversations, having a voice, giving opinions, offering reviews, and generally interacting with content and with each other like never before on the web. How can we enable users to respond to or contribute to user assistance? The answer could be a wiki, but a wiki is not required to enable more interaction with users. Here are some specific techniques, starting with the simple and moving towards the more complex, including wiki implementation practices.

Embedding Comments    Link to contents

While the simplest techniques have low barriers to entry, they also have low commitment levels from users. Comments in social media are powerful conversation feedback loops. Your business goals may differ in the level of engagement you expect to need with customers. While blogs offer comments naturally, your help site may not contain a comment system. To enable customers to give feedback, you can offer comments on each help topic. Comment forms give users the opportunity to respond to the topic in addition to striking up conversations with each other. Some commenting systems are as full-featured as a forum.

If you want to encourage conversations on your HTML-based help site, you can embed a comment form at the bottom of help articles using a product like JS-Kit ECHO, which has a low entry-level price of $12 annually. In addition to online identity and comments, JS-Kit ECHO also offers methods for people to share the content on different platforms. With Echo Pro, you can even support an existing login, such as for your customer support site. Once you register a domain name to use JS-Kit, you'll get Javascript code that you embed on topics where you want to enable comments. Here is an example:

<div class="js-kit-comments" permalink=""></div><script src="http://js-kit.com/for/www.domain.com/comments.js"></script>

JS-Kit ECHO comment form

Figure 1: JS-Kit ECHO comment form

A nice feature of this example is the ability for commenters to identify themselves with different accounts. Online identity matters to people who comment, to your company, and to you as a help writer. By offering an online identifier, you will encourage good behavior online. Anonymous commenting systems do not offer as useful feedback, and are prone to spam. This system also avoids the "Yet Another Login" syndrome that might deter people from registering to comment.

A similar comment form offering comes from Disqus, and there is no charge to use the service. Even bloggers as well-read as Robert Scoble are substituting their "out-of-the-box" comment systems with Disqus for its additional identity, threaded conversations, and moderation features. Once you register for a Disqus account, you can enter the help site address that you want to have embedded comments. Drop in the customized "embed code" anywhere on your help page and configure some settings.

Disqus comment form (no styling)

Figure 2: Disqus comment form (no styling)

You can use CSS styles to make the form adhere to your site's look and feel standards. Disqus and other commenting systems offer threaded discussion, which helps users follow back-and-forth discussions about the content.

Some traditional user assistance tool providers such as MadCap Flare offer a ratings system and comment capability called a feedback form on each topic. You install additional server-side applications to collect the data yourself.

Disqus and JS-Kit store the comments for you, but JS-Kit offers a way to host your own comments if you are concerned with security. For all of these implementations, the site must be available on the Internet.


  • Conversation goes back and forth for all to see, and users can get to know you and each other through comment threads.
  • Ratings help you make strategic decisions about content - what needs improvement, what is doing well without further revision.
  • Comments can offer readers more in-depth explanation.


  • Comments are only useful to those who speak the language a comment is written and displayed in.
  • Comment threads can be long, so long that the critical nugget of information can get buried in a thread.
  • Negative comments must be addressed and handled with care.

Tagging and Sharing    Link to contents

Tags are labels on content on the social web. Tags are used for photos, videos, bookmarks, and blog entries, to name just a few uses. Tags offer a unique display mechanism called a tag cloud. Tag clouds show the labels, or keywords, in larger or smaller font sizes based on the amount of content labeled with that tag.

Tag Clouds and Tag Rolls    Link to contents

Bookmarking services like Delicious offer a way to generate Javascript that you can insert into a web page to display their tags. Called a "tag roll," it lets you display tags for any user on delicious.com and offers a variety of display options. (See http://delicious.com/help/tagrollsExternal link). For even more control over the visual display of tags, you can use the Wordle.netExternal link website. You can create a tag cloud from a list of words, from an RSS feed, or by entering a user name from the DeliciousExternal link site. Wordle tag cloud of 100 tags for annegentle username on Delicious.com

Figure 3: Wordle tag cloud of 100 tags for annegentle username on Delicious.com. (Image attributed to http://www.wordle.net/External link)

You can also copy and paste keywords into the Wordle interface to create an image. This technique is effective for presentations, graphical displays of keywords, and other visual embellishments.

Content Sharing    Link to contents

You could add a sharing capability to your user assistance, so that users can tag your content and share it with others. A popular free tool for content sharing is Add ThisExternal link. Implementation is as simple as registering on the Add This site and obtaining configurable code to add to your site. You can configure which external sites are listed with buttons for users to share the content with others. You can grow your content's "reach" by enabling sharing through social sites, potentially assisting even more users.

Add This button for sharing web content

Figure 4: Add This button for sharing web content

This article itself uses an Add This button on the WritersUA site. Try it for yourself to see all the social networks on which you can share this article, and share it, please!


  • With many wiki engines, users who appreciate categories (Mediawiki) and labels (Confluence) can do tagging for you.
  • Gives another view of your content that may help users find what they need.
  • In an "attention economy" where links are the currency, your help site can get boosts from links to the site through shared tagged bookmarks.


  • While they do not need to be as strictly monitored for consistency as index entries, tags require maintenance.
  • Folksonomies, which are taxonomies created by ordinary folks, can complicate lists of tags when taggers use the gerund form, plural form, or additional forms of a word that complicates the meaning. It's helpful to guide the community towards standard tags.

Syndicating    Link to contents

Syndication of content through Really Simple Syndication, or RSS, offers users up-to-date information directly from your site. There are two ways to look at syndication. One is to offer an RSS feed of your content from a wiki or content management system to notify users when content has changed. Another RSS offering is to embed results from an RSS feed into your user assistance, like a scrolling news feed.

Google offers a way to create and display snippets dynamically from feedsExternal link. You simply configure options on the configuration screen, then generate code. You can embed that code directly, or you can further configure the exact RSS feeds that you want to display. In this example, the URLs could be modified to change the feeds that are displayed:

<script type="text/javascript"> function LoadDynamicFeedControl() {
var feeds = [
{title: 'Informatica',
url: 'http://www.informaticaondemand.com/index.php?format=feed&type=rss'
{title: 'Enterprise data integration',
url: 'http://www.b-eye-network.com/blogs/business_integration/rss_feed.php'
{title: 'Information technology',
url: 'http://www.ist.rit.edu/?q=rss.xml'
var options = {
stacked : true,
horizontal : false,
title : "Informatica News"

Example of dynamic content from RSS feeds

Figure 5: Example of dynamic content from RSS feeds


  • Content is constantly updated as long as the provided feeds remain active.
  • Enables links to conversational web content such as blogs.


  • Click-throughs on syndicated content could take readers away from your site.
  • Requires that end-users have Internet access and that filtering on the content does not prevent it from displaying.
  • You have no control over headlines from other sites, bloggers, news feeds, and so on, so choose your feeds wisely.

Collaborating    Link to contents

To tighten the connection between customers and the company, you may want to move from indirect collaboration methods to more integral and direct collaboration with customers. Offering collaborative authoring platforms, like wikis and web content management systems, enable people to bring their experiences and scenarios to the content system. They give readers the ability to rate content, correct errors, and contribute their own articles. The combination of an active wiki plus a powerful search engine could be the ultimate content collection and collaboration point for enterprises. Yet in reality, wikis are not always well suited for the types of content we create in user assistance. Suppose your company's IT department has already selected a wiki that doesn't work well for your technical support content or online help. Can you gracefully house your content there despite a flawed tool set? It depends on a multitude of factors, such as the amount of programming resources needed, the motivations of contributors both internal and external, and the patterns of adoption your company can implement. Can you retrieve some useful content from a wiki and re-purpose it? Let's explore some possibilities for practical collaborative authoring and content re-purposing using wikis.

Selecting a Wiki    

Wikis offer great speed for publishing revisions of content, plus review turnaround can be shortened. With a low barrier to participation, wiki authoring gives teams the opportunity to rapidly prototype new content from any author, even users, depending on security need. Many companies also cite the need for cheaper, faster, direct engagement and feedback from customers as a good reason to move to a wiki or web CMS. In fact, when users clamor for notifications when help content changes, a wiki is an excellent solution.

However, wikis sometimes get people on edge. They evoke memories of editing wars and loss of control of your content. Yet, wikis are basically just specialized, simplified web content management systems. A wiki and a web content management system will have similar features, but wiki engines were originally built to be simple. Wiki engines are crossing over into the content management system arena. For example, Confluence is listed on both comparison sites.

Whether you're considering a wiki or a web content management system, you should match up your requirements for delivering user assistance with the specifications for certain wiki engines. The websites CMSMatrix.org and WikiMatrix.org list hundreds of web CMS and Wiki products and let you compare features. Perhaps collaborative authoring is high on the priority list. Maybe you need to get product documentation onto the Internet. Your users may want notifications or the ability to add content. For their organization needs, technical writers likely want hierarchy for the wiki articles. For legal purposes, they may want a wiki with access control lists. Some technical writing teams offer trusted, tested content on one wiki available to just a handful of contributors, and have more open editing access on another wiki. Also, choosing between database systems and file systems may make maintenance easier for some people. Twiki and MoinMoin are file and directory-based wiki engines. Twiki, which is what FLOSS ManualsExternal link uses, affords implementers both hierarchy and access control lists. MoinMoin allows for parent, child, and sibling relationships, represented as directories in the file system and access control lists are integrated. MediaWiki and Confluence are both database-driven wiki engines. MediaWiki was not designed to accommodate per-page access restrictions. Confluence has three levels of administration from global permissions to space permissions to the ability to enforce page-level restrictions. Take some time to gather requirements, possibly using established techniques like personas, to make sure you select a product that works for your business.

Documentation Wikis    

Some documentation teams using wikis use the Confluence, MediaWiki, and MoinMoin wiki engines. It's no coincidence that WebWorks ePublisher offers conversion from FrameMaker, Word, and other inputs to these three wiki engines.

Here are some examples of documentation delivered through wikis:

While migrating your content to a wiki is another article in itself, here are some ideas to get you started. Look for XML and in particular, DITA, as strong intermediate storage formats. One proven method is to export to DITA, then use the DITA2Wiki toolExternal link to build to a Confluence wiki. This method generates labels for the content, and a table of contents automatcically from the DITA map. Another method is to use the WebWorks ePublisher product to take your FrameMaker or Word files (and other supported inputs) and publish to Confluence, MediaWiki, or MoinMoin. There is also a RoboHelp to MediaWiki toolExternal link available for download. Confluence has a Word import tool that works quite well. Also, you can use an HTML to wiki converterExternal link that converts to Confluence, MediaWiki, and MoinMoin among many others.

Wikislicing    Link to contents

Wikis can be the authoring tool, the delivery mechanism, or both. To be an effective delivery mechanism, you need to consider how to create different kinds of deliverables from your wiki. One answer is wikislicing. What is wikislicing? At its simplest, wikislicing involves taking some articles in a wiki, and creating a collection. The collection can then be extracted as a PDF file, a flat HTML file, or a wiki for delivery. Effectively your wiki could be a single source of content from which you (or your users) can create cross-sections or wikislices for deliverables. This allows writers to write in the wiki and then either a specialized user assistance expert or an architect "slices" it based on labels, categories, or spaces, depending on the wiki engine.


To see examples of MediaWiki wikislices, see the selected wikislices created already for the One Laptop Per Child projectExternal link, such as the Great Wall of ChinaExternal link, Space explorationExternal link, and the Brothers GrimmExternal link. The toolchain for such wiki slicing was not a packaged product until the InfoSlicer projectExternal link was created for Sugar. (Sugar is the education platform that runs on the OLPC computer.) InfoSlicer creates educational curriculum out of Wikipedia articles, using DITA as a transport layer and DITA maps under the covers to organize the articles.

InfoSlicer gathering of Wikipedia articles for educational use

Figure 6: InfoSlicer gathering of Wikipedia articles for educational use

With the correct use of categories in a MediaWiki wiki, you can slice the wiki based on audience, language, or content type such as grouping tasks, reference, or concepts. You are basically retrieving a group of articles based on a cross-section of your wiki - a wikislice.

To use categories in a MediaWiki page, you edit the article and add special coding to add it to a category. For example, add "[[Category:Admin]]" on the page source anywhere. You can also add the Select Categories extension on MediaWikiExternal link to help editors choose from existing categories.

Once your content has categories applied to it, you can use the MediaWiki Special Export toolExternal link to create an XML file containing all the content. On your wiki, the page address is http://servername/mediawiki/index.php/Special:Export. You can enter a category name or a list of pages that you want to export.

Special Export page on a MediaWiki installation

Figure 7: Special Export page on a MediaWiki installation

With programmatic help, you can transform the exported XML into HTML or PDF, but unfortunately, the article content itself remains in wikitext, and is not exported as XML. The Help:Export pageExternal link offers some tools and methods for processing the exported XML.

However, for PDF exports, the MediaWiki project has already packaged up a PHP-based content converter into the PDFBook extensionExternal link. With administrator access to the MediaWiki server, you can install this extension to enable PDF creation from your collection of wiki articles. Here are the basic steps for enabling PDF exports from a MediaWiki site.

Installing and enabling PDFBook on MediaWiki

Do these steps on the server where MediaWiki is installed.

  1. DownloadExternal link and install HTMLDoc.
  2. DownloadExternal link and install the PDFBook extension into the Mediawiki extensions directory (typically mediawiki\htdocs\extensions).
  3. Modify your LocalSettings.php to include this line (typically stored in mediawiki\htdocs):
    require_once( "$IP/extensions/PdfBook/PdfBook.php" );
  4. If your exported PDFs are going to be created from a collection that is larger than 100 articles, also modify this line in the LocalSettings.php to allow 64MB memory for PHP:
    ini_set( 'memory_limit', '20M' );

Integrating PDF downloads on your MediaWiki site

This extension's most basic implementation is a simple URL that you can create for any category to be downloaded as a PDF book:

http://www.domainname.com/wiki/index.php?title=Category:Admin&action=pdfbook where the category you are using to export the book is all articles with the Admin category applied.

You can also link directly to a large HTML page using a similar, simple URL: http://www.domainname.com/wiki/index.php?title=Category:Admin&action=pdfbook&format=html

You could design your landing page with these URLs created for specific collections, such as Configuring, Getting Started, or Installing books. See an example of such a landing page on the Open Office wikiExternal link.

Also, on each page of your wiki, you can include a template that offers a graphic and a link indicating that the articles can be downloaded as a PDF or a collection of HTML files. Including the contents of one page into another is called transclusion, and the help topic on Templatescode for the following exampleExternal link can be viewed online.

PDF download example as a template on a wiki page

Figure 8: PDF download example as a template on a wiki page

The PDFBook extension can use these indicators, such as title of the book or author, in a template. Using a template in MediaWiki basically means you put the name of the template enclosed in double curly braces in the article's source. You can create templates in MediaWiki just like you do a wiki page - by using the wiki's URL, adding the template name to the URL address, such as adding "Template:Book" to the URL. After landing on the new page, click the Create or edit this page link to create the template. Here are the available parameters for including in a book template:

{{Book |name = [[***]] |author = [[***]] |publisher = *** |buy = *** |ISBN = *** |keywords = *** |image = [[***]] }}

You can enable users to create their own books with the Extension collection. You can see this tool in action at simple.wikipedia.orgExternal link - look for "create a book" in the sidebar.

Configuring the PDF layout is simplistic, but you can control the margins, the font, and the levels of heading allowed in the table of contents. Refer to the PDFBook ConfigurationExternal link section in the extension's documentation for details.


If you are using Confluence, you can create PDF files from your wiki either from a part of a space or from an entire space, if your login has the "Export Space" permission. The online Confluence to PDF pageExternal link offers detailed instructions.

You can style the PDF by using the PDF Stylesheet which is also documented in detail on the Atlassian wiki-based documentation. You must be a space administrator for that space or be a Confluence system administrator to modify the PDF styles, but once you modify them, all PDFs created will conform to the same style. The Confluence documentation covers step-by-step instructions for editing the PDF stylesheetExternal link. And to bring the discussion about users in user assistance full circle, you may also join in the comments discussions at the bottom of the pages on the Atlassian Confluence wiki documentation site.

Summary    Link to contents

I hope these examples provide some hands-on exercises that you can try with your own content. These are just a few examples of the scenarios that are possible when you think of user assistance as a user connector. Ideas abound in my book, Conversation and Community: The Social Web for DocumentationExternal link from XML PressExternal link. Join me in putting the user into user assistance.

Anne Gentle currently works as a community publishing consultant, providing strategic direction for professional writers of all kinds. She wrote the book, Conversation and Community: The Social Web for Documentation and writes a blog at JustWriteClick.comExternal link. She is a documentation maintainer for FLOSS Manuals, a wiki-based collaborative publishing platform and writing community.


Copyright © WritersUA. All Rights Reserved.
shannonm *at* writersua *dot* com


WritersUA offers cutting-edge training and information to Technical Writers, Information Analysts and Architects, Documentation Designers, Help Authors, Publication Managers, Documentation Leads, Senior Writers and Documentation Contractors, and User Education Specialists. The focus is on software user assistance, which encompasses writing, editing, planning, coding, indexing, testing, programming, localization, and standards development.

WritersUA Home Page First Time Here Contact Us Join Our Mailing List OASIS Member RSS Resource Directory Tools Contractors Training Articles Blogs Web Resources