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.

Since I don’t want anyone saying I didn’t share it with them, here’s a picture for your enjoyment. 

What are you talking about Ben?

Oh, you don’t know this story?  Sit back and I’ll get you up to speed.

Back in 2008, Google Chrome was released and quickly became the hottest browser on the web.  Throughout 2009, more and more users took a shine to Chrome’s minimal UI and fast execution.  Built-in debugging tools made web developers giddy.  Life was good.  Except for one small issue.

You see, Chrome implemented all the latest web technologies and touted itself as being extremely secure.  Which was certainly true, unless you happened to access local file content with the file:// protocol.  Then, all bets were off.

As usually happens, a bug report was filed and tracked:

Issue 4197 – Further restrict access of file URL

The defect was finally fixed in February, 2010.  The updated Chrome browser made its way out to folks in March, 2010.

The result was… not what people expected.

• File based Google tests for O3D samples and WebGL conformance == broken
• File based JavaScriptMVC == broken
• File based WebWorks Help 5.0 == broken
• File based WebHelp (most every help vendor out there) == broken

The same content, served up on a webserver, performed beautifully.  It just stopped working when accessed from the local file system.  This change to Chrome’s handling of the file://protocol hit anyone who made use of JavaScript with framesets or iframes.

Think help tool vendors, open source projects, end users, tech pubs == A Lot of People.

Is this the right thing to have done?

Maybe.  It depends on where your focus lies.  Google is focused on the Internet.  Chrome is focused on the Internet.  So the fact that Chrome is now fairly useless as a desktop browser shouldn’t come as a big surprise.  I just wish Google would tell everyone and disable support for the file:// protocol in Chrome.  Better to say “That’s not supported” instead of “Maybe it works, maybe it doesn’t”.  Build a set of HTML files with JavaScript that obey every security requirement for web content, and you have zero guarantee that the same content will work when accessed from your local file system.

Google did give us a heads up about where they might take Chrome back in 2008 with a blog post entitled Security in Depth: Local Web Pages.  I guess we can’t say they didn’t warn us.

What is WebWorks doing about this issue?

We already clicked that little star icon for Google’s current defect .  Now, we’re working on how best to make sure customers can continue to leverage ePublisher’s WebWorks Help output on the desktop.  One way to accomplish this is by using Internet Explorer only on Windows.  Details on the WebWorks Wiki.  The other path to success is to find a way to deliver help using the limited environment Google offers.  This is going to take a while longer to accomplish, if such a thing is even possible at all.

What can you do about this issue?

For starters, you can check out Google’s defect:

Issue 47416 – Allow a directory tree to be treated as a single origin

Hit the star icon in the upper left corner to let them know this matters to you.  Please note that commenting has been disabled and the existence of 11 merged defects.  Next, you can consider requiring IE or FireFox for your help content.  If you are using the WebWorks Help API, you can configure it to always use IE instead of the system’s default browser.  Other possibilities include generating simpler help output, using the Dynamic HTML format, or building native help.  Microsoft HTML Help 1.x comes to mind for Windows based applications.  These changes are easy to make with ePublisher (just add a new target), but difficult to integrate as they change the packaging and help APIs established for your products.

What else can you do?  Talk to me.  Leave a comment.  Let’s see if we can find a solution for everyone, together.

I’d like to figure out how we can better address both types of customers in the future.  Doing so might mean splitting AutoMap into distinct products.  Let’s see if we can define some product offerings that better fit everyone’s needs.

I’ll start off with a list of functions AutoMap presently provides:

• Scheduled generation
• On-demand generation for scripting integration
• CMS integration capabilities
• Pre/Post generate actions (useful for source-control integration)
• Notifications (E-mail)

Our Sales team tells me they have a further need to distinguish between:

• AutoMap on a server
• AutoMap on a client

Here, the server case represents AutoMap being used as a centralized resource by a number of users.  The client case represents customers looking to keep their Express projects up-to-date or integrating AutoMap into their nightly build processes.  Obviously, we’d like to find a way to provide a client-side user with a reasonably priced offering.

Finally, there are always the things that AutoMap doesn’t quite do yet, such as support for job queuing.  Job queuing would ensure a system could not be overwhelmed by multiple, simultaneous conversion requests.

Tell me now.  If WebWorks were to build one or more products based upon the AutoMap of today, what combination of functions would you need for success in your organization?

Recently, I blogged on our approach for validate market directions with sketches (Sketching the Future).  Now I’ll show you how we are working to locate those potential directions.  Our goal for each market is to simply understand:  Is anybody out there there?

ePublisher’s flexible nature and open architecture mean the platform is often used to address a wide variety of publishing challenges.  The only limitations to creating solutions are time and effort.  How can we find the right ones?

Here’s a list of ideas that we believe have potential value as part of the ePublisher platform:

• ePub eBook production
• Jive community server support
• SharePoint wiki support
• Mobile optimized websites

We will be linking to these pages (and others like them) in our newsletters, Google Adwords campaigns, etc., and learning from people’s actions.  See something you like?  Click through and learn more.  Not your thing?  Then exit the page.  All of this information helps us learn which topics resonate with visitors.  The goal is for us to see if we are hearing and understanding people’s requirements for the ePublisher platform.

A big part of this approach is ensuring we are ready to engage customers before we invite their feedback.  Right now, we just want to see what people are reading and clicking on.  Next, as we find promising areas to explore, we will extend those topics with simple surveys to help us validate our understanding.  Finally, as we move into sketches, prototypes, and early access builds, we will post sign-up forms which let you know we are ready to engage you directly.

Net result?  A better ePublisher.  An ePublisher that meets a growing market’s needs.

Lately, I’ve been working with the rest of the WebWorks.com team to improve our process for realizing the future.  We started back in 2009 with the RoundUp 2009 feedback session.  This year, I asked for reader’s help in last month’s Focus, Focus, Focus blog entry.  Those ideas have been added to the great material users submitted as enhancement requests on the WebWorks wiki since 2006.

It’s time to start turning those possibilities into reality, one sketch at a time!

For those of you wondering just what the heck “one sketch at a time” means, allow me to explain myself.

Last year I attended SxSW Interactive 2009 here in Austin, Texas.  It was a great experience.  I took several lessons away from my time there, as well as a copy of Bill Buxton’s Sketching User Experiences.  Bill’s book talks about creating sketches, quick experiments which can let users see a potential value, interact with it, and then think about how the world might be if such a product were to exist.  Sketches are a great way to fail faster.

Applying Bill’s lessons to WebWorks.com, I could clearly see our sketching skills left much to be desired.  We committed to shipping new features with relatively little market feedback.  We did not do a good job of asking customers, “How could feature X help you in your environment?”  Instead, we put features on the road map, built them, and shipped the result.  Imagine our surprise when those features turned out to be less valuable in practice than they were in theory.

Things haven’t always been this way.  Certainly, ePublisher Express grew out of extensive market research to understand how to improve publishing workflows in customer environments.  Heck, ePublisher, and Publisher before it, grew from the strength of user ideas shared on wwp-users.  We can do it.  We’ve done it before.

The challenge we face today is the sheer size and scope of our products.  We have a huge customer list.  We have a vast array of features.  ePublisher includes support for three distinct authoring environments.  DITA itself is no small feat to corral (DITA 1.2 anyone?).  Thus, our efforts are spread across an ever expanding range of technologies and environments.

To address this challenge, we worked hard over the last few years to bound complexity.  We limited release lifetimes, from “whatever” down to 2 years and 8 active releases.  Further, we found ways to help our users keep up with us.  The introduction of legacy format support in ePublisher 2009.3 is a great example of this effort.  Now, we’re taking the next step by using the power of sketches to refine our understanding of user expectations.  This approach, in the form of descriptions, demos, webinars, or one-off builds, will enable us to learn  and do more than ever before.

So I’m warning you now.  We’re going to push a lot more ideas out in front of you in 2010.  We’re going to try a few crazy experiments.  And we’re going to learn, one sketch at a time, how to increase ePublisher’s value for everyone.

As validating as it was to receive that feedback, concerns were expressed regarding the pace of ePublisher releases.  The message?

Slow down!!!

This issue, our quarterly release schedule, has come up before.  I’ve heard it mentioned by attendees during our RoundUp conferences in 2008 and 2009.  Folks simply felt overwhelmed by the prospect of rolling out a new ePublisher release within their organization every quarter.  They could see it stretch out before them, quarter, after quarter… after quarter… after quarter.  They loved the new features and bug fixes we were making available.  They just wanted those releases paced every six or twelve months rather than every three months.

First, let me say loud and clear, “I understand”.  Back in 1997, I took at two year break from WebWorks.com (Quadralay to you old timers) and worked at Tivoli Software.  Tivoli had recently been purchased by IBM.  It was a place with vast resources and a customer base who faced daunting deployment challenges .  To give you an idea of what they were up against, consider this..  One of Tivoli’s customers managed 36,000 systems world-wide with Tivoli management software.  It took somewhere on the order of 18-36 months to roll out a new release.  1 1/2 to 3 years!?!  This was a time frame that shocked me.  This was such a big chunk of time that folks working on the project retired.  Others went from burping newborns to wrestling with two year olds.  And the computers they worked on were getting replaced completely (most had three year leases).  Coming back to WebWorks.com in 1999, I brought with me an appreciation of what organizations are up against when it comes to deploying new software releases.

So, what about ePublisher and quarterly releases?

First, the lesson from Tivoli was simply this: Customers can’t/won’t pick up every release. Organizations need to pick a time frame that works best for them.  With quarterly releases, we let you run as fast as your needs dictate.  The quarterly cycle ensures we are moving users away from having to rely on workarounds created in Support.  They get to ditch those short-term fixes and move on to out-of-box product.  This helps everyone because out-of-box products are easier to deploy and maintain than a product with workarounds.

Second, keep in mind that WebWorks.com supports ePublisher releases for a minimum of two years.  That means, if you’re running ePublisher 2009.1, as long as your support contract is active, we’ll help you keep 2009.1 running throughout 2010 and into 2011.

Finally, to help you decide when the time is right to make a switch, we provide you with all the information you need.  We take care to document the major changes for each release series (see 2008 and 2009).  We also provide detailed release notes.  Our goal is to provide you with everything you need to make an informed upgrade decision.

So what do you think?  Do we have the right approach?

What are we going to ship THIS quarter?

Marketing is analyzing, Sales is requesting, and Support is demanding.  And on the other side of those groups are our customers.  Some, we will delight. Others will curse our names, shocked to find that we have chosen a challenge other than the one they face.  The choices are never easy even when the strategy is clear:

All we have to do is choose wisely.

Here’s a summary of what’s on our plate:

• Enable per Target settings in the Style Designer
• META data and keyword marker support (for formats other than WebWorks Help 5.0)
• PDF library update
• Research environment specific issues affecting PDF production
• Work-arounds for FrameMaker instabilities
• Windows 7 certification

And then there’s the list of things that COULD be on our plate:

• DITA Open Toolkit 1.5 integration
• XSL-FO processor alternative to Apache FOP
• Ignore files extension list (for Stationery creation, file copies, etc.) to avoid version control issues
• Conditional Expression Builder UI for FrameMaker 8, 9 users
• RoboHelp migration path
• WebWorks Help replacement (faster loading, cleaner design)
• Support for custom index markers
• Wiki projects
• …

What would you choose?

A partnership Ben?

Yes.  A partnership.

Well, that term partnership implies work, and I’ve got enough on my plate.

Really?  You too!  Gosh, I thought I was the only one.  ;->

Alright Ben, I get it.  You’ve made your point.
I can help out a bit.  What do you need me to do?

I need you to keep doing what you’ve been doing all along:

1. Use ePublisher.
2. Tell us about your problem.

Now, we’ll add just one more step:

Show us the problem!

Let me tell you about a little something I call the Car Talk Syndrome.  On the NPR radio classic, Car Talk, people call in and ask the hosts to help them fix their broken cars.  And sometimes, these guys can help them right away.  Other times, they tell callers  “Go see your local mechanic”.  I mean, it’s a car, right?  Sometimes you just have to see the problem first-hand.

Here at WebWorks.com, folks ask us questions too.  (It’s just like Car Talk except we use email, a case system, and we aren’t syndicated.  Otherwise, it’s exactly the same.)  So, like Car Talk, we can sometimes answer a question right away.  The rest?  We need you to show us those up close.  That’s when we encounter the dreaded Car Talk Syndrome.  Folks are convinced that talking about their problem is the same thing as having it running on our systems.  We kind of feel like the local mechanic who has been asked to fix a customer’s car while it sits at home in the garage.  Instead of the car, the customer brings pictures instead.

See right here?  That’s where my cousin backed his riding lawnmower into the side panel.  What do you think?

What do I think?  I think you’ve got a problem.  What am I gonna do about it?  Actually, right now, there isn’t much I can do about it.  Maybe crack open a beer and comment?  “Yep, you’ve got yourself a problem there.”

So, just like you need to bring your car to your local mechanic if you want it fixed, we need you to bring your problem to WebWorks.com.

I can do that…
I know how to do that…
Actually, how do I do that?

Easy! Open a Support case.

When you open that Support case, you create a mini-workshop.  A place where our Support staff and you can work together to reproduce and understand your problem.  Then, when it’s time to get help, Development can focus on fixing the exact issue that is causing you grief.  Since you took the time to work with us, we get you up and running as soon as possible.

And then you’re happy…
And then we ship the fix in the next release…
And then you’re really happy…
And then other people (who didn’t report the bug) are happy…
And then you get a raise because you’re so much more productive with ePublisher…
And then …

You see, we’re preparing to ship ePublisher 2009.4.  And 2009.4 isn’t about features.  It’s about making the best ePublisher 2009 release possible.

Why am I writing about this?

Because I promised folks we’d include just one new feature in 2009.4.  It’s a great feature.  Something that increases ePublisher’s flexibility and power.  The problem is that it is just too complex to ship in a maintenance release.  The feature I’m talking about is the capability to define per target style settings.

“We’ll just shim it in there,” I told Jesse.  “No sweat.”

That was back in November.  Back before.  Before we spent hours and days wrestling with PDF defects.  Before we spent weeks chasing workarounds for Frame crashes which we could only bypass, not fix (we don’t have access to that code base).

And so I have to let it go this round.  I have to let people know, “No, not this time.“  There really is no other choice.  The time has been spent.  It was spent on exactly what we needed to do; stability.  It’s just that I like creating new things.  I don’t want to let go.

…

Then again, once 2009.4 ships, all that maintenance work is done.  And if 2009.4 is done, then we can focus on 2010.1.  And we can put new stuff in 2010.1.

…

I think this is going to work out alright after all.