Delivering More than Text


December 2010

Delivering More than Text

CIDMIconNewsletterMysti Berry with Dean Atchison and Joanne Ward, has always produced context-sensitive help, standalone HTML help and guides, and PDF help and other guides, along with the occasional workbook and quick reference card. In the last year we’ve also produced or started work on new types of information: videos, guided tours, and even a comic book. My colleagues, Jo Ward and Dean Atchison, and I will share with you why we turned to these output types, how it all worked, and what lessons we’ve learned in the process.

Guided Tours

Our team creates guided tours for some new features. Guided tours are a series of pop-ups with explanatory text as shown in Figure 1. Jo Ward on our Documentation team says that they are “an engaging way to introduce new features on a single interactive page.”


Figure 1: One Popup from a Guided Tour

Guided tours contain basic guidance to show immediate business value—they don’t explain every feature, contain unique information, or replace help. A guided tour answers several questions about a feature or sub-feature.

  • What is this feature/sub-feature?
  • Why should I use it?
  • Where can I find it?

To help writers create guided tours, Jo Ward worked with our User Experience team to create a design pattern to help writers choose the appropriate titles, text, and links. Writers work with product managers and developers to ensure that no single page in the application has too many guided tours. Users can choose to hide the guided tours permanently or view them later. Guided tours always end with links to related videos and the online help. The tours are “pushed,” that is, they automatically pop up when the user navigates to the application page until the user clicks a control to permanently hide them.

To help with translation into 12 languages, text for the guided tours is kept in label files, just as the regular UI text is. Guided tours supply a text-only version for accessibility.

The framework that supports guided tours was created by a developer on the UI team who worked with the Documentation and User Experience teams. The code is adapted by each feature team as needed. Several writers on the team provide support and expertise to writers who create a guided tour for the first time, especially around issues working with developers who add the guided tour to the application.

Why Guided Tours?

The User Experience team responded to customer requests with the proposal for guided tours and then partnered with the Documentation team to seek buy-in from the Development, Quality Engineering, and Product Management teams. Since the guided tour is automatically displayed, it solves the problem of a user having to navigate through help topics to find something, or worse yet, not know there is something to find. We’re working on ways to collect metrics on the use of these guided tours, but so far anecdotal evidence supports their continued use.

We decide which features or sub-features to support with guided tours by determining the anticipated learning curve for a new feature. Features with new, complex, or unfamiliar user interface interactions are prioritized.

Lessons Learned

It’s important to perform thorough editing to ensure that the tour is focused on the business case, not too software-focused. Also the text in the guided tour must be concise and use an engaging, informal tone.

It’s not appropriate for every group or feature to have a guided tour. Because they are pushed, not pulled, it could be frustrating for users to see too many tours. We have a team that edits and reviews tours for each release to check for tone and to ensure that we don’t have too many guided tours in one product area.


Dean Atchison from our Documentation team helps writers create videos. He tells the story best:

“We started creating videos based on customer feedback. A common thread started appearing in our user surveys that customers wanted videos in addition to standard documentation. We realized that we live in a YouTube generation and our users learn in different ways. Some want to read; others want to watch.

“We first focused on creating videos (see Figure 2) for new features, and it was really up to the writers whether they had time and interest to add a video to their already busy schedules. We have created a few videos for legacy features, and I’d like to focus more on this area in upcoming releases. Ideally, I’ll prioritize which features get created based on various customer inputs. For example, what features do our customers search for most in our help? What features and behaviors generate the most support calls, etc?


Figure 2: Frame Capture from a Video

“At first we used Adobe Captivate to create videos and hosted the videos on our Salesforce servers. Now we’re starting to create our videos using Camtasia, which I’ve found is easier to use for non-interactive demos, and we are beginning to deliver our videos over YouTube.

“Some teams are more excited than others about videos. We rely on the writer

[assigned to the feature] to spearhead the entire effort. We generally don’t need buy-in from Product Managers, but since we do need some help from developers to check in the video and create the video link in our application, we like to have the entire team on board.

“We did run into a few cases where Marketing created similar videos. However, for the most part there hasn’t been too much overlap because Marketing focuses on overview videos that raise awareness and sell our features, while the Documentation team focuses on shorter “how to” videos that help the user accomplish a specific task. We’re now actively partnering with Marketing and other teams to coordinate video creation efforts.

“At first, I established standards and a general process for other writers to follow for their videos. I created wikis, trained writers on Captivate, answered their questions, reviewed their scripts, and set deadlines. As the number of videos we created grew, I formed a team of three or four writers who were experienced with videos and teamed each of them up with the writers responsible for creating videos for the current release. The “video buddy” concept worked well and allowed us to scale our efforts.

Lessons Learned

“At the end of the day, I’m really glad we’re focusing more on videos. Our customers want them, and almost every writer is excited to participate in creating a video for a feature. Videos have also increased the visibility of the Documentation team in other groups like Marketing, Support, and Training.

“If you’re serious about creating videos, you need to make a fairly big investment in terms of time and resources. What was once just a side job for me is now over 50 percent of my time—and even that’s not enough. Given the high number of customers who are asking for videos and how much they raise the visibility of the Documentation team, I think the investment is well worth it.

“Writers do require training on Captivate, and it can take a while for people to learn how to write a good script and add the bells and whistles that make great videos. Another issue is voice talent. Some people have a great natural-speaking presence while other folks have to practice to achieve the right inflection and tone. I think it’s a good idea to identify the people who have great speaking voices early on and reserve their time. That being said, I also think most people can learn how to have a great speaking voice—it just takes time (which is something we don’t always have).

“One of the issues I think our industry faces is how to remain relevant in the Web 2.0 world. In the age of Google, blogs, and community forums, are people still reading our docs? I think videos are a great way for us to increase our relevance and footprint. We can upload videos to YouTube so customers can easily find them and link to our videos from blogs and in community forums. Videos are a great way to make our customers happy and increase our own job satisfaction.”

Comic Book

I was lucky enough to receive the comic book assignment. The comic book form has been used in technical documentation occasionally. The most famous, recent example is the Google Chrome comic written and illustrated by Scott McCloud, who is the ambassador of comics, having written the classic Understanding Comics. He interviewed about 20 developers at Google and then created an introduction to the product in comic book form in 2008. However, the Google Chrome comic is not in narrative or “story” form; rather, it explains the product with illustrations of the developers explaining their portion of the product. This format is helpful for extremely technical discussions.

My outside-of-work experience with narrative story forms in general (screenwriting, short stories, and novel) and my experience helping my husband with his graphic novel series made me the logical person to handle our first request for a comic book. I decided that we should use a narrative or story format for a less technical issue. We wanted to help developers who use the platform understand which types of tools to use for particular needs. For example, administrators and developers can use point-and-click tools or a programmatic language or build their own client application using our API. The comic follows a developer at a company as she moves from challenge to challenge and, with a little advise from our mascot Sassy, builds solutions with the right tools, becoming a superhero to her fellow employees. Because of time constraints, another talented fiction writer on our team, Garen Torikian, wrote a lively and amusing script from a story outline I provided.

We hired an experienced comic book artist (See Figure 3) to transform the script we wrote into sequential art. Because we were discussing the product at a fairly high level of detail, Product Marketing needed to make sure our comic book aligned with the Product Marketing messaging, and we are currently in the midst of a rewrite to accommodate those needs.


Figure 3: Early Pencil Sketch for Comic Book

Lessons Learned

People get very excited about the idea of a comic book, but very few people understand the requirements of sequential art or storytelling, so it can be difficult to get buy-in from stakeholders. Additionally, very detailed technical information is not always easy to work into a narrative story. You may wish to take the “illustrated document” approach as Scott McCloud did. Otherwise, be sure that you identify a clear customer need that can easily be expressed in a dramatic question, such as “how do I know which tool to use for which problem?”

Also, we found that identifying an artist who had actual comic storytelling experience was more challenging than we expected. Corporate messaging might require that you avoid violence or dark themes, which are the bread and butter of comic storytelling. Finding an artist with strong skills who can also make a static setting such as a software company interesting to look at without resorting to sex or violence is not trivial.

Finally, be ready for such a project to attract a lot of attention in your company—everybody loves comics! You must be very sure that you have properly identified all the actual stakeholders for your comic project. Once an artist commits to a particular layout, only minor modifications can be made to the story: changing the size or shape or sequence of a single panel throws the rest of the book off. If a stakeholder weighs in too late in the process, you might need to start over with the artist.

Final Thoughts

Documentation teams are being challenged to do more with less. Although these projects do take writing resources, their impact on customers can be well worth the investment. CIDMIconNewsletter

Mysti BerryMysti Berry

Mysti Berry, MFA, is an award-winning technical writer with more than 20 years experience. She lives in San Francisco.

Dean Atchison

Dean Atchison has been a freelance and staff technical writer at companies large and small for the past 15 years. He lives in San Francisco.

Joanne Ward

Jo Ward is a technical writer and manager who has worked at small and large companies in the UK and in the Bay Area for 15+ years. She lives in San Francisco.