Tailoring the DITA Suit to Fit: How we adapted title and shortdesc standards to help our customers love our release notes

DITA has standards for titles. DITA has standards for shortdescs. They tend to be siloed from each other and generic in their prescriptions for use. Over a two-year period, the writing team at Salesforce has evolved the existing standards into our own set of title and shortdesc guidelines for a specialized content type—release notes for each triannual release of the Salesforce SaaS product. These release notes give customers advance notice and detailed information about upcoming product enhancements so that they can prepare themselves and their users.

Our release notes have different requirements from most DITA content because of the release notes’ purpose—to focus on each release and not on Salesforce functionality overall. They’re time sensitive—What’s new this release? And they have the important job of conveying the business value of each new feature—Why should I care about feature X? They are also voluminous, and customers rightfully complained about having to read through all 300-plus pages to try to assess which new features they wanted or needed to know about.

In response, a small team of writers set out to revamp the release notes to make them more effective at doing their job. We worked extensively with all the writers to help them adopt DITA best practices for using topic types and the title and shortdesc elements. And we coached them in shifting their emphasis from documenting a feature to conveying the business case for it. Our work facilitated a separate effort to make the release notes available in a searchable, filterable HTML format—a huge plus for customers.

The combination of title and shortdesc proved to be the linchpin we needed to make it really easy for customers to find the information they cared about. We started with a 12-page draft of title and shortdesc writing guidelines for both online help topics and release notes. As we worked with writers over the months, we distilled our insights into a one-page handout that is now pinned to the corkboard above every writer’s desk. Getting the guidelines adopted by a hundred writers—with varying levels of familiarity with DITA—is an ongoing challenge.

What can the audience expect to learn?

See how you can take DITA best practices further to suit your unique needs. You’ll learn from our example of rolling out writing guidelines to a large, distributed team of writers somewhat unfamiliar with DITA best practices. And you’ll leave with copies of the guidelines, which you’re free to share and adapt.

Meet the presenters

Cate de Heer

Before joining Salesforce in 2012, Cate de Heer had writing and editing roles at Adobe, Intuit, and McGraw-Hill/Random House, and as a consultant. Working with a wide range of startups, corporations, nonprofits, and public-sector agencies, she has planned and developed UI text and instructional content for users from developers to students to seniors. Coaching other writers may be her favorite skill to use. Cate has a bachelor’s in French language from the University of California, Davis.



Liane Yee

Liane Yee has been a technical writer at Salesforce since 2010. Previously, she held documentation roles at Yahoo! and Right Media. She began her career as a policy analyst, consultant, and business analyst, working in the areas of solid waste, community economic development, and building code enforcement. She has a bachelor’s in Environmental Sciences from the University of California, Berkeley.


⇐Return to Agenda