Reuse Strategies to Support the API-ification of Your ContentFirst Steps

Mysti BerryPrincipal Content Strategist

@MystiContent

in/mystiberry

@MystiContent

• Technical Writer for 20 years

• Content Strategist for 3 years

• Big DITA fan

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.

Today let’s discuss

• What I mean by “API-ifying your content,” and why it’s

important

• How API-ification can save your company money and

earn your company money

• Roadblocks to API-ification

• First steps to remove roadblocks and prepare content,

using examples from our work at salesforce.com

Caveat

I don’t have all the answers, especially the technical ones.

I do know that entangled content stops even the best solutions, like DITA, from exploiting content assets for new form factors, content combinations, and locations.

What Do You Mean, API-ify?

What does API-ify mean?

Storing your content in small enough units, with predictable

internal structures, so a machine can grab any combination

and pump it out to a new delivery channel without writer

intervention.

API-ification requires:

• Predictable structure within topics

• Well-defined taxonomy/subject scheme/metadata

• Magic API elves to pump that content to multiple

destinations in limitless variation. Without error!

With an API layer, your content is everywhere!

Content in small topics, with associated metadata

Content API Layer

Content

response

to

customer

behavior in

all form

factors

Code

complete

in text

editors,

IDE, UI

forms

Rollover

hints in

UI, doc,

training,

internal

code

Integrate with

customer

content

“Show me”

interactivity

Labels

Video

Mobile

overlay

Why API-ify?

• We used to write books. Handy for scoping by audience.

• Then we wrote helpsets. Hey, isn’t search GREAT?

• Now?

Why API-ify? Because future!

Not just a device proliferation issue, which DITA handles.

Social media changed customer expectations• Just what I need to know

• Just when I need to know it

• Preferably, show me before I need to know

However, “psychic” is not in our skill set!

Why API-ify? Because customers!

Do your customers:

• Simultaneously complain about too much and not

enough information? They aren’t crazy.

• Ask for open source docs so they can roll their own?

• Turn to third parties to explain your products to their

customers?

(No customer feedback? Getting it is Step Zero.)

Why API-ify? Because experts!

Content strategy empresaria Karen McGrane tells the NPR

story very convincingly.

Credit: http://mfglabs.com/charles-darwin-and-apis/ For more: Karen McGrane & NPR

How API-ification Can Save and Earn Money

How can API-ification save money?

• Lowered support costs: gold-file quality content prevents

calls. Especially if it’s in the app, not in an HTML silo.

• Lots of labor savings, because content is created once,

never refactored.

Technical documentation groups are great at creating

accurate content. If it’s reused, not rewritten, it stays right.

#TechPubsGetsCuration

How can API-ification earn money?

• Charge customers for content integration.

• Great content closes sales.

• Great content prevents attrition.

Roadblocks in the Content

Content isn’t consistent

Machines can’t parse snowflakes

Content isn’t modular

Content lacks external metadata

• Why external to the topic? It’s easy to overload topics

with metadata requirements: imagine 30 values times

10 different qualities you want to capture. Plus filtering.

• It’s also hard to go in to each topic and change values

when the metadata changes or a new value is added.

Note: We’re experimenting with subject schemes to

automate mechanical tasks and show ways to dynamically

deliver content.

Removing Roadblocks

Required: disentangle reuse

What we did: as part of a now-or-never re-architecture

project, writers removed all inline links that crossed

“bundle boundaries” in the help. We can now publish

parts:• Learn Salesforce Basics

• Set Up and Maintain Your Organization

• Analyze Your Data

• ….

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

about 4,000 help topics.

Figure out a better navigation than XREFs

• Inline links may be a patch—fix the problem and the

need for the entangling link goes away:• Point reader to the right place in the UI, not to a help topic.

• If content really needs to be there, CONREF it in from a

resource file, don’t link to it.

• Fix the architecture so you don’t need the link. (Difficult)

• You may be hand-coding stuff that DITA can provide

(<shortdesc> + linking=“normal” is *easy*; keys)

Solutions 1 of 4: get them back in the UI

• Instead of:

<xref>Enable Email-to-Case and configure your

Email-to-Case settings.</xref>

Solutions 2 of 4: CONREF instead of link

VS

Solutions 3 of 4: Fix the real problem

Do readers want a million paths, or one?

Solution 4 of 4: Use DITA smarter

• Example: Auto-generate container navigation topics.

• Example: Use keys to simplify filtering.

• Example: Experiment with subject schemes to generate:

Solution 4 of 4 Page 2: Use DITA smarter

• We have a Limits & Limitations guide, which we had to

create manually, because:• No consistent metadata (external or internal), so machine can’t

find all the limits and limitation topics.

• No consistent internal structure, so machine can’t pull out the

limits and limitations from topics with other content.

Without these roadblocks, we’d have an automatically-

created resource instead of burdening writers with

“remember the limits guide!” I want the future, now!

Removing roadblocks: summary

• Get reader back in the UI, not off to another topic.

• CONREF instead of XREF.

• Fix the real problem.

• Use DITA smarter.

Biggest lesson: we can guess, but we should test our

guesses with metrics. Try something new in a troubled

topic, see if you can improve pageviews/satisfaction.

Next Steps to Content API

After removing roadblocks, build it!

API-ification = single-sourcing ++

• Predictable structure within topics

Consistency like you get with forms-based authoring!

• Well-defined taxonomy/subject scheme/metadata

We’re experimenting with subject schemes. What else?

• Magic API elves to pump that content to multiple

destinations in limitless variation. Without error!

You need developers, QA, product manager—you’re really

building a product that you can sell.

Please please stay in touch! The future is so close!!!!!

Mysti BerryPrincipal Content Strategist

@MystiContentmberry@salesforce.com