The Reverb Effect

WebWorks Reverb - Lessons in Content Delivery and Findability

by Ben Allums
May 15, 2011

I've worked at WebWorks for nearly 14 years. In that time, content delivery costs and methods have changed significantly. WebWorks Publisher enabled technical writers to escape the joys of hand-coded WinHelp files. Browsers opened up the web and enabled sophisticated HTML help run-times. Google made it possible to find your heart's desire in the world wide world. Today, the Social Web lets you find what you need with the help of people you trust.

So all you have to do is put your content on the web... Right? Well... Perhaps there are a couple of more things to consider. Lessons learned and validated by what we experienced here at WebWorks: The Reverb Effect.

Over the past few years, we've had a number of customers use our WebWorks Help format as a content delivery vehicle to reach their audiences. WebWorks Help has been a reliable workhorse for content delivery since 2000. It runs in a variety of browsers and offers users a familiar, full-featured help experience.

The only problem with WebWorks Help is that it doesn't play nice with search engines like Google and Social sites like Facebook. It turns out, very few help-focused systems do a good job on these tasks. For example, we realized back in 2006 that sites like Flickr pulled tricks on the URL hashtag (#) to allow bookmarking content on a dynamic site. So, we added that capability to WebWorks Help. Later on, we received feedback from our customers that getting search engines such as Google to index WebWorks Help content was not straightforward. WebWorks Help makes heavy use of JavaScript links and processes. All this was required to support 4.x series browsers and their limitations. However, supporting older browsers meant that Google was blind to our content. We introduced a workaround for this problem in 2010 that has addressed the issue for most users.

Even with all of these changes, getting content found still wasn't easy. We've even been posting our documentation up to (our documentation wiki) to gather feedback from users. And yet, if users did search for help, they wound up in our legacy documentation area!?!?!

What was going on?

Turns out several factors led search engines (and by proxy, users) to consider legacy docs as being “more authoritative” than our wiki and WebWorks Help-based content.

  • Simple HTML pages – Limited navigation, such as TOCs, to improve search engine content ratings.
  • Single HTML page feel – Must be quick to load, lightweight.
  • Simple HTML links – No JavaScript tricks. Search engines could see the internal structure of the content.
  • Direct page links – The URL the search engine crawled matched the URL the user bookmarked, copied, etc.
  • Consistent search experience – Our wiki-based content relied on a wiki-specific search engine once users arrived at the site. It's just different from how users arrived there == Not Google.

We decided to take these lessons to heart and build a new information delivery system for a new Internet era. We called the system WebWorks Reverb and tied it to the ePublisher 2010.3 release. Well, that took a bit longer than we expected to deliver, so ePublisher 2010.3 made it out the door in January 2011, instead of October 2010. As part of that release, we posted our documentation to the web in the new Reverb format.

Shortly after release, we noticed an amazing thing happening: users were finding our Reverb-based content on the web! And not just here and there. Support almost immediately switched over to sending users links into our Reverb documentation, despite the documentation wiki being the “official” support vehicle. Users on ePublisher mailing lists were finding the documentation as well. The best part was how the perception of our documentation transformed. Comments changed from “couldn't find the answer I was looking for. WebWorks needs to redo their docs” to “found what I needed!” It was the same documentation, only in Reverb format versus a wiki! Oh, and people were actually leaving real comments! More comments in 2-3 weeks with Reverb than in the previous 2 years with our wiki.

To top it off, we found our documentation was leading our website traffic, outstripping marketing rhetoric for traffic, read times, and reduced bounce rates. About that same time, Sarah Maddox blogged on her own experiences with documentation on the web at Atlassian. Her results matched ours, though she does have 1 or 2 more site visitors than we do. :-)

We wanted to share what we've learned through Reverb with everyone in the technical communication space. These lessons apply to web content in general. They are not specific to WebWorks Reverb. So, as part of STC's 2011 Conference, WebWorks will be talking to folks and showing them how these few simple lessons transformed our own content from wallflower status to MVP player. You can talk with Jesse Wiles in our case study session Making your Help Findable on the Web, or swing by our booth to learn more.