Climbing Out of the Weeds: Moving from Generic to Specialized Topics

Mysti BerryPrincipal Content Strategist

@MystiContent

mystiberry

We Started with a Lovely Garden Plan

Before DITA:– FrameMaker books for Help, API Guide, a few miscellaneous things

– Topic type = chapter or long topics (busy UI pages)

After DITA:– About 2,000 XML files (Perforce is our CMS)

– Writers never have to make the same change by hand in different

branches.

– Reuse even easier than with FrameMaker

– Topic type = <topic>

– 10 writers, two portals, 90% non-overlapping topics

To be honest, there were weeds from Day One

Massive ad-hoc reuse = ticking time bomb

Information types mixed up in single topic files

Nested topics in a single file

I’ll always regret saying, “Oh, that’s going to take forever to

untangle. Let’s just convert as is, and fix it later.”

For example…

Is this structured?

Is it all concept?

All reference?

Hidden tasks?

Reuse is hard:

Ad hoc conref

“English Only” mismatches

Filtering

Weeds Choked the Garden

Some writers spent hours diagnosing content issues that

caused build failures.***

Writers had to choose between not reusing content, or

spending hours or days refactoring mixed content.

Ad hoc conrefs made reuse hard.

***We have weekly and quarterly publishing cycles, three

branches, continuous auto-integration. We’re fanatical

about checking in “clean code.”

No Hay Problema – Enter The Info Model Team!

Whole team trained in Information Model by Ms. Hackos

Team led by our Information Architect Steve Anderson

Development done “in our spare time”

Invited volunteers staffed the team

We have a culture of innovation, a long habit of spinning up

SWAT teams, and an Agile mindset. What could go wrong?

Results

Over a year later, we had an Information Model!– Topic type definitions and guidelines: <task>, <reference>,

<concept>; <topic> only if desperate

– Deliverable type definitions and guidelines

– Patterns

– Templates

Trained writers on how, but the “why” was hard to grasp

We didn’t require they use new topic types

Didn’t restructure existing generic topics: $$L10N$$ limits

Information Model Flopped (a bit)

Incomplete before we could publish it (adding new

deliverable types all the time)

Writers struggled to reuse existing, unstructured content

Despite templates, writers gave up quickly when:– Asked to create many more files than they used to

– Asked to write in a highly structured way—epic <shortdesc> battle

– Faced with “task can’t conref into generic topic” problems

– A few issues w/templates and unforeseen problems: task

Some managers encouraged writers to ignore new model

Another year later and…

2,000 topics had become 5,000 topics

30 writers—less than a third of us had the full training

Three document portals, some with shared, filtered content

Doc Tools team challenged by high demands (More portals!

More deliverable types! Support more writers!)

Some writers believe in the myth of three clicks

Our architecture reinforced “documenting the architecture,

not the user goal.”

Did I mention, structured writing is really hard?

Your turn: create a compelling <shortdesc>– Topic title: Prerequisites for Fooing a Bar

– Body: a list of the prerequisites, no intro <p>. Prerequisites are for

being able to use the quick-start code in the first chapter of a

developer guide for FooBar.

– Does this need a <shortdesc>? Does the title answer both ‘what

does this topic tell me’ and ‘why do I need to know it’?

To sum up:

We had a lot of content problems blocking specialization.

Writers were unconvinced that they needed to write in a

more structured way. They didn’t believe little tiny topics

add up to customer satisfaction.

The Info Model Team needed to roll over to other duties.

Meanwhile, two team members attended a Content

Strategy conference (Confab), and managers heard a lot

about it at conferences like this one.

Hey, Let’s Get a Content Strategist!

We had two (now three) dedicated full-time resources on

build processes and tools, but no one focusing on content

at the global level

Tech Pubs teams typically do content strategy as part of our

day jobs: but some things are left abandoned in a fast-

growing group

Finding content strategists with enterprise-class tech pubs

experience (much less cloud experience) was challenging,

so we finally hired from within

Tweaking the Information Model

Add One Full-time Content Strategist

Owns a backlog of issues – writers have someone to

listen to them, to track issues, and advocate to resolve

content issues

Guides doc efforts aimed at existing unstructured

content: audits and advice

Can focus on repairing information model– Fix broken or missing elements

– Reintroduce info model to team

– Fill in belief gaps

Started with lots of goodwill

I’d been a writer for 20 years, at Salesforce for five

years. Team knew I knew the challenges

Worked on the API doc, which meant working with

nearly every other writer on the team at some point

I’d been hollering “we need a good content strategy” for

at least a year—whether or not I knew what that meant!

High visibility from successful projects, lots of goodwill

Repair work

Presented intentions to the whole team

– Info Model is here to stay

– 3-click limit is a myth

– Not everyone believed me at first (huh!)

– Director confirmed “Info Model no longer optional”

Fixed issues with templates

Added missing deliverable types

Interviewed all 45 writers to ask about their concerns—

turned the common themes into my backlog

More repair work

Invited anyone interested to join new Info Model Team

– Goal: provide coverage, person-hours to do the work

– Spread knowledge and skills across team

United Style team and Info Model Team– Bugs against style guide sometimes require Info Model weigh-in

– Common goals to create easy-to-reuse, consistent content

Added office hours for Info Model questions– Work with writers 1:1 to clarify subtle issues of structured writing

—success breeds enthusiasm

– Coach writers on “follow the user’s path” not “doc the feature”

More repair work

Created videos for writers’ pain points

– Easy way to create lots of topics, add them to ditamap

– How to use task topics (reuse content in multiple deliverables)

Consulted with teams set to tackle “legacy issues”– Ensure audit efforts are focused & productive

– Deliver guidelines for what to tackle, publish to rest of team

– The team taught me what to do: set their priorities, scoped what

they could do, made a backlog

Start Liaison Work with Rest of Company

Joint projects with Support

– Support and help topics in same repository, require a single

taxonomy

– Ongoing maintenance of taxonomy

“Customers for Life,” Other Initiatives– Some marketing folks interested in Content Strategy

– Training, many other functional groups generate content for

customers—resolving terminology clashes, look-and-feel

issues, etc. challenging without a dedicated role

How Successful Are We?

Are Things Better?

We’ve gone from about 10% of new topics being

specialized to about 95%

Writers are asking more “how do I” and less “why do I

have to” questions

Teams are tackling hard problems like how to go from

ad hoc reuse to resource files

Other teams reaching out to doc more because they

have a single point of contact

Lessons Learned

Don’t wait to fix structure issues

Don’t wait too long to go from <topic> to specialized!

Structured writing is harder than unstructured

Some writers need convincing that short topics are good

Whether or not the person is titled Content Strategist,

dedicate someone to curate content in big company

Include the writers at every stage: they know where the

bodies are buried