Abstract: Salesforce.com developed a formal Information Model several years after converting from FrameMaker to DITA. The writing team has struggled to understand how specialized topics work, and how to implement them with existing generic topics that often lacked structure. Ad hoc content references inhibited our ability to update existing topics. We employed a content strategist to redeploy the Information Model. Technical communications groups typically perform content strategy without the help of a specialist, but the demands of rapid growth, Agile development, and weekly deployments required a dedicated resource to: - Identify content issues disguised as tools or organizational problems Facilitate communication between highly-skeptical writers and the overburdened tools team Implement solutions that take full advantage of DITA&apos;s strengths
Moving from unstructured to generic topics is a common strategy. Our portals were help & training window in the app, and a public-facing server for dev doc.
Choosing Object Relationships first bullet is a task! The second bullet is tightly bound in a way the bullets aren’t in the first section. If there’s wifi: https://help.salesforce.com/apex/HTViewHelpDoc?id=reports_schedule.htm&language=en_US Our brave Analytics writers are tackling this topic as we speak!
Explain English-Only problems. # 3 is filtering issue—repeated content to avoid breakage.
Unforeseen problems: task has a lot of unique elements. Conrefs to/from quite difficult when 80% of your content is in &lt;topic&gt; More about the epic battle in a minute!
Everyone on the Info Model team assumed writers would all embrace structured writing—but by the time of the rollout, over half of them had never had the training. Structured writing is very different from unstructured, challenges you to ask harder questions than when you just “doc the UI.” Also, many writers believe in the myth of three click limit.
Nearly 10,000 topics, less than 300 have shortdesc. We ended up with: You need access and appropriate permissions to completethe code example.
What about my customers, call center folks. They need answers now! From the one page of context sensitive help! I have to dump it all there! DITA can give the illusion of structure.
Abandoned things include: taxonomies for search in our own doc portal (had to align with Knowledge Base), SEO concerns, how do we fix generic topics? Care and feeding of Info Model—who makes sure needed changes are implemented? Who measure success and provides support to struggling writers.
Style question: when do we use &lt;shortdesc&gt;? Info Model answer (encoded in style guide): when it’s not clear “why” from the title. Success stories: Pavi & ISVforce, Ted and omniture, people want to do smart things, fix hard problems
Climbing Out of the Weeds:
Moving from Generic to
Principal Content Strategist
We Started with a Lovely Garden Plan
– FrameMaker books for Help, API Guide, a few miscellaneous things
– Topic type = chapter or long topics (busy UI pages)
– About 2,000 XML files (Perforce is our CMS)
– Writers never have to make the same change by hand in different
– 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.”
Is it all
Reuse is hard:
Ad hoc conref
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?
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
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
Finding content strategists with enterprise-class tech pubs
experience (much less cloud experience) was challenging,
so we finally hired from within
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
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
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
– 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
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
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