We’ve prepared a short two-question survey based on your technical writing role. We’ll release the results once we have everyone’s responses.

TAKE THE SURVEY NOW >>

We want to hear from you!
Comment on this blog post and let us know what you thought about this whitepaper series.  Do you agree or disagree?  What do you think the future holds for technical writers? 

STEP 1: Add WebWorks Reverb to your ePublisher Pro Project >>

STEP 2: Enable Disqus in your Format Settings >>

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 straight-forward.  WebWorks Help makes heavy use of JavaScript links and processes.  All this was required to support 4.x series browses 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 docs.webworks.com (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, light-weight.
• 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 re-do 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 wall flower 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.

Next we follow up with “When”. Inspecting the log becomes essential at this point. On the log screen you will see various stages of output generation.  Let’s say that you run across issues during the Image pipeline. If your inconsistent errors are consistently happening at the Image pipeline, most likely there is something going on with the graphic generation, which leads into the “What” question. So, in our example we determined that it happens at the graphic pipeline.  So, what aspect of the graphics are we trying to isolate? Is it an issue with the Rasterizer? These are things that can be tested by using by-reference images in your input.  Once you determine what is the cause of the graphic culprit, you can begin to ask the final question, “Why?”.  These can be as simple as needing to close a dialog box, however if you cannot figure out why it occurs, then chances are you will not be able to resolve this.  Sometimes, you might get lucky and the issue goes away, but we want a better success rate than chance.

Ultimately, the goal in Support is being able to reproduce and isolate issues. Given system specific issues, isolating is an absolute must.  How can we fix something that we know nothing about? If you have submitted a case, and it seems like we are asking many questions, there is a reason for it, and the reason is that we are trying to help you as quickly as possible.  Also, feel to share any troubleshooting insights that you have.

This is one of those really fun Windows errors do to a limitation in the paths up to 268 characters.  The especially interesting thing about getting this was due to the fact that I got this for every project consistently, so likely it is something that was messed  up with the installation, right? Wrong.  NO, this is something you have to fix at the Windows level.  What I ended up doing to resolve this was go to the Local Settings:  C:Documents and Settings[myusername]Local SettingsTempWebWorksePublisher and clearing this out. After the hours of anguish of uninstallation, installer cleanup utilities and re-installation, the answer was to just delete some temporary files.

By all means, if you are getting an “Object reference not set to an instance of an object” error, this would be something that we should look at in the product. Chances are, however, if it is an error like the one above, there is something going on in Windows that can be resolved quickly and hopefully painlessly. Happy troubleshooting!

More often then not, however, I end up feeling like this:

It would be nice to be an evangelist of pushing up your sleeves and getting dirty within customizations, however mostly it is just re-explaining things that are found in the product or perhaps difficult to find.  For better or worse,  I am the bear. Typically this means that once a person can formulate a question well enough, then that means that he/she can usually figure out the issue.  Sometimes this happens as early as attaching a test case, so that I can help this person figure out the issue through troubleshooting.  Digressing a little, people sometimes ask me why they have to attach a test zip to the case. This goes back to the mechanic metaphor. Would it not make sense that you drop off your vehicle when getting it diagnosed by the technician?  Sure you could try the “Car Talk” approach, but in all reality, we really need to actually see this issue before we can begin to work on it.  It just doesn’t make sense if there is something wrong to not be able to look at it first hand, so in that sense I am more like the riveter.

I don’t mind being the bear, though, really.  Trial and error can be an arduous process and sometimes the right training can ease the process of learning new software.  Also Support has been working with Documentation to provide feedback on the new ePublisher docs via the Reverb format.  For our more advanced users, if I can’t provide a satisfactory answer, I will usually point these people to the Wiki for a chance to submit their own projects, that or the Power Hour/Study Hall sessions for the informal training that we provide.  Even for me as someone who researches problems every day, a chance to reformulate my questions on how to use or customize the software can be helpful.  Everyone gets stuck sometimes, and it is okay to want to have a pink care bear to ask your questions.

http://wiki.webworks.com/HelpCenter/Tips/RelatedLinks

Of course, anyone can be provincial, but the reality is that producing output in different languages is key for many helpsets. The fact that most systems are not unicode-ready will most likely lend to some troubleshooting.  In this particular case, I was having difficulty on only a Japanese system with FrameMaker 9 version.  When working multiple operating systems and different languages, it can be useful to create a table of the combinations in order to know what you have and have not tried. Here is an example of this:

As you can see, ePublisher 2010.2 is the constant, while there is combination OS/Language and FrameMaker/Browser version  that I used.  It can be daunting troubleshooting these different variables, but having a visual representation can be helpful for both Support and Engineering.

We just posted an application and wiki entry for a new experimental FTP deployment client for ePublisher. Anyone interested in using FTP(S) for deployment, please give it a go and give us feedback.  Please comment either on the wiki page or this blog post.