Herding TigersLetting Go of Inline Links

Mysti Berry

Principal Technical Writer

@MystiContent

in/mystiberry

@MystiContent

@SingleSourcing

About the Speaker

• Technical Writer for 2 decades

• Content Strategist for 2 years

• Currently on Internal Doc team

Safe Harbor

Safe harbor statement under the Private Securities Litigation Reform Act of 1995: This presentation may

contain forward-looking statements that involve risks, uncertainties, and assumptions. If any such uncertainties

materialize or if any of the assumptions proves incorrect, the results of salesforce.com, inc. could differ

materially from the results expressed or implied by the forward-looking statements we make. All statements

other than statements of historical fact could be deemed forward-looking, including any projections of

subscriber growth, earnings, revenues, or other financial items and any statements regarding strategies or

plans of management for future operations, statements of belief, any statements concerning new, planned, or

upgraded services or technology developments and customer contracts or use of our services.

The risks and uncertainties referred to above include – but are not limited to – risks associated with developing

and delivering new functionality for our service, our new business model, our past operating losses, possible

fluctuations in our operating results and rate of growth, interruptions or delays in our Web hosting, breach of

our security measures, risks associated with possible mergers and acquisitions, the immature market in which

we operate, our relatively limited operating history, our ability to expand, retain, and motivate our employees

and manage our growth, new releases of our service and successful customer deployment, our limited history

reselling non-salesforce.com products, and utilization and selling to larger enterprise customers. Further

information on potential factors that could affect the financial results of salesforce.com, inc. is included in our

annual report on Form 10-K for the most recent fiscal year ended January 31, 2011. This document and

others are available on the SEC Filings section of the Investor Information section of our Web site.

Any unreleased services or features referenced in this or other press releases or public statements are not

currently available and may not be delivered on time or at all. Customers who purchase our services should

make the purchase decisions based upon features that are currently available. Salesforce.com, inc. assumes

no obligation and does not intend to update these forward-looking statements.

Put a Link On It

Today We’ll Discuss

• What’s wrong with inline links

• What we did to remove unnecessary inline links

• How the team responded

• Best practices if you’re thinking of purging links

What’s Wrong

with Inline Links?

What’s Wrong with Inline Links?

• Links slow every reader slightly, and slightly decrease

comprehension as measured by recall.

• Links are clicked between 0%-8% of the time in our highest viewed,

lowest rated topics. Maps get 20%-35% clickthrough at best. (More

research needed)

• The resource manager in some tools is painful, takes writers a few

minutes per link to create.

• Refactoring content that contains links is a nightmare.

• If we rely on manual, inline links, we’re not looking for better

solutions.

Lesson: We’re spending time and money on resources that no one

uses, resources that slow down every reader, and help very few.

How Bad Was It?

• Our doc builds were slower because of inline links.

• Many topics triggered a build of topics not in the

ditamap because of entanglement.

• More than a few circular references, unnecessarily

disjointed topics.

• Writers want to refactor content, but embedded links

turn a four-hour task into a three-day job.

Example of Excessive Links

Scent of Information Grows Faint…

Scent of Information Grows Fainter Still…

Wait…where am I?

If We Couldn’t Use Links, We Would Write This

Better?

What We Did

What Did We Do?

As part of a now-or-never re-architecture project, I asked

writers to remove all inline links that crossed “bundle

boundaries” in the help:

• Learn Salesforce Basics

• Set Up and Maintain Your Organization

• Analyze Your Data

• ….

We removed 4300 inline links, or 46% of them. We have

about 4,000 help topics.

Sounds Easy, But Not So Much…

• We had hundreds of ditamaps, thousands of topics, and

thousands of manual, inline links.

• We had to evaluate each link in each topic. We hit user

limits on Google docs just tracking things.

• We had to choose:

• Delete the link because it really wasn’t necessary.

• Do something because the link really was necessary.

“Necessary XREFs”

• Readers would suffer loss or corruption of data if they

didn’t follow the link.

• Readers couldn’t complete a task without the link. For

example, some steps in a large task contain complex

subtasks.

If an XREF was within the top-level ditamap, it could stay.

If it pointed to a topic outside that ditamap, we had to do

something.

Question: If an XREF is necessary, why isn’t the content?

Solutions 1 of 3: Get them back in the UI

Solutions 2 of 3: Conref instead of link

Steps 3 and 4 contain information shared across several

topics.

Solutions 3 of 3: Fix the Topic

Depends on what’s wrong:

• Can you send the user back to the UI?

• Is it an overstuffed topic?

• Are we focusing on the customer’s path through the

product?

There was very little time for real refactoring/redesign of

topics in our project. We didn’t do enough analysis of

the problem topics.

How The Team Responded

Some content creators LOVE to delete stuff

Some content creators HATE to delete stuff

It’s Hard to Let Go of Links

• My team of brilliant and empathetic writers want to help

every customer. It’s hard to see that sometimes helping

the few (0-8%) actually makes it harder for the 90%.

• Our Information Model encourages small topics, so a

link seems like the right solution, especially under time

pressure.

• We have tasks that span features, so writing doc is like

when you fix your sink and then have to run to the

hardware store. That’s hard to do without links.

We Didn’t Find All the Answers

• Features start out as isolated, become app-wide

service. How can we revise the basic structure of docs

as product and feature definitions change frequently?

• We require help link on every UI page. But customers

aren’t clicking some of those links. What do you do?

I Failed To Persuade the Tigers

• One hack day project recently discovered that in our

most viewed, most disliked topics, customers click links

8% of the time or less. But this hasn’t generated any

new enthusiasm for deleting links in favor of content.

• There’s a movement to use DITA chunking to article-ize

small topics together in one HTML output—which for

some content may be a great idea! If overused…?

• Some writers are truly frustrated with the link limitation.

We’re Still Not Looking for Better Structure

• “It’s been hard to hear from my cube…that these topics

are awful. I put an entire release into taking those topics

from 5 page scrolling walls of text into concise,

complete map topics, and all of that effort was quickly

undone in [the work to remove inline links].”

• “…we heard from a few users in our usability sessions

that in task-of-task topics, seeing steps that are simply

statements of what needs to be done without links to the

relevant topics can be confusing.”

Some Writers Have Put Links Back!

This is an often-visited, low-rated topic with many customer

comments. What could the writer have done aside from add the

links back in?

Do Links Address These Comments?

• not helpful I want to delete an opportunity - ? how?

• i need to arrange the group based on close date or

stage, etc. I am looking for the definition of closed date

on the opertunity screen. i found no useful information

on this question here.

• does not tell me how to do any of the items from the

error report!

• Was trying to see if you could actually sort the various

Opportunities columns by Opportunity Name. Above

comments weren't very relevant.

Best Practices for Purging

Unnecessary Links

Why Bother?

• You need to COPE (create once, publish everywhere).

• You can’t COPE with entangled content.

• Downstream processes break with too many inline links.

• You have to do a lot of manual work for every new combination.

• Refactoring existing content takes 10 times as long as it should.

• Because mobile…

You Can’t Herd a Tiger (or a writer)

But They’re Fierce Customer Advocates

So just make it easy, and clear why it’s a good thing:

• Check your metrics before proposing style or guideline

changes. Try some experiments first.

• You can’t say this too many times: “We were making the

best guesses we could. Now we have more information.

It’s not you. The requirements have changed.”

• You must give writers alternatives like “get them back

to the UI as quickly as possible” or “move that to a

resource file and conref it in,” and then make it easy.

Invest in Project Management

• A manager spent a lot of time organizing us by

spreadsheet, auditing our content to size the project,

and running agile-style meetings to keep us moving.

• Analyze the thorny problems before you begin.

• Attack a small hunk of content at a time. We couldn’t, as

most of the topics were so entangled with each other.

• Try writing a new doc in the new style and sharing

metrics with writers first.

If You Aren’t in XML/DITA Yet

• Get rid of links before you convert from FrameMaker.

• Make your content as structured as possible before you

convert.

• Don’t go crazy with reuse. Establish guidelines so you

don’t become entangled. Most important guideline for

help: don’t publish reused material (keep it in resource

files). Doesn’t always work for reference documentation.

Mysti Berry

Principal Technical Writer