The document discusses how Salesforce adapted DITA standards for titles and short descriptions (shortdescs) to better suit release notes. Key changes included writing titles in the imperative to show customers new capabilities, focusing shortdescs on what's new rather than descriptions, and addressing only administrators and developers rather than end users. Guidelines emphasized covering all key changes and prioritizing comprehensiveness over length. The presentation reviews challenges in implementing the guidelines and ideas for continued improvement.

1. Tailoring the DITA Suit to Fit
How We Adapted Title and Shortdesc Standards to
Help Our Customers Love Our Release Notes
Cate de Heer
Liane Yee
1

2. Forward-Looking Statements
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 product or
service availability, 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, new products and services, 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, the outcome of any litigation, risks associated with completed and any 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 and in our quarterly report on Form 10-Q for the most
recent fiscal quarter. These documents and others containing important disclosures 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 presentations, 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.
2

3. What’s Salesforce?
We help you sell, service, and market smarter.
3

4. We produce a suite of customer-facing docs.
4

5. Customers count on our release notes three times a year.
Salesforce admins use
them to:
● Decide what new
features to set up
● Prepare their users for
changes
5
https://releasenotes.docs.salesforce.com

6. Admins have to learn what’s new and make choices.
6
What training or advance
warning do my users need?
Should I set up and
roll out to my users?

7. We used to provide exhaustive detail about everything.
Detailed setup instructions + detailed tasks for end users = TMI
7

8. We knew: Less is more.
Customers just wanted to know:
What’s new here?
And why should I care about it?
8

9. Ted had a vision.
Let’s use structure to show customers the big picture, and let them drill down.
9
The release notes would tell
the story of each release.
And every customer would
get to choose their own
adventure through the notes.
The key?
Shortdescs.
https://twitter.com/tedkuster

10. Shortdescs would also support filtered navigation.
10
Customers could narrow navigation to topics they cared about.

11. But early shortdescs didn’t support progressive disclosure.
Challenges:
● Dozens of writers across
departments
● A history of very
distributed content
development
11
Apex Test Runs
Apex test runs have been enhanced.
Writers were starting to use shortdescs, but they were fuzzy about why.

12. We also knew: We needed
guidelines.
12

13. Our starting point: Review industry standards.
What guidelines did DITA experts offer for writing shortdescs?
13
There is an art to writing short
descriptions, or crafting them, as
is probably a better way of
putting it. The best approach
seems to treat the short
description as a “thesis
statement,” which leads to more
effective, expository
descriptions.
Tony Self, author of The DITA Style Guide
Introduce the concept and answer
the question “What is this?” and
“Why do I care about this?” If the
concept is unfamiliar, start with a
brief definition. Avoid using the
short description to lead in or build
up to a topic… Do not simply
repeat the title.
http://docs.oasis-open.org/dita/v1.2/os/spec/langref/
shortdesc.html

14. We eventually distilled our guidelines into a 1-page handout.
14
Key takeaway: For the
strongest information
scent, write the page title
(h1) and shortdesc together.

15. How did we augment the DITA
standards for release notes?
Two principles:
●We address only admins and developers, not end users
●We focus laserlike on what’s new
15

16. (Title + shortdesc) addresses a use case.
We don’t leave it to customers to extrapolate business
value from a mere description.
16
Impact on
voice and
tone
Apex: Stop a Test Run That’s Failing Miserably
Large runs of Apex tests sometimes take longer than we’d like them to. Waiting for a
run to finish only to learn that many of your tests failed can be irritating. You can now
configure test runs to stop executing new tests after a given number of tests fail. No
need to waste your time waiting for the results of a run that you’re going to rerun after
fixing issues in your org. You can set how many tests can fail in test runs that you
execute both in the Developer Console and using the Tooling API.
Apex Test Runs
Apex test runs have been enhanced.
BEFORE
AFTER

17. We write page titles in the imperative.
To show customers: What can they do with Salesforce now?
Apex: Stop a Test Run That’s Failing Miserably
Task List: Power Through Your Tasks
Exception: Passive voice for ordinary or expected changes.
Salesforce1: No Longer Supported in iOS7
Even though they’re concept topics.
17
Impact on
voice and
tone

18. In page titles, we lead with the name of the product area.
Provides context; complements breadcrumbs and filtering.
18
Sales: Opportunities, Leads, and More (product area)
Productivity: Do More with Lightning Experience (sub-area)
Home: Manage Your Day in Lightning Experience (feature)
Task List: Power Through Tasks in Lightning Experience (feature)

19. 19
● Cover all key aspects of
what’s new or changed.
● Prioritize
comprehensiveness over
length limit.
● Don’t leave big surprises
for the body or child
topics.
Shortdescs are concise but also comprehensive.
Shortdescs complement titles to maximize the scent of information.
You can now allow role-based external users, such as users with
a Customer Community Plus or Partner Community license, to
approve records.
You can now allow role-based external users, such as users with
a Customer Community Plus or Partner Community license, to
approve records. If you don’t want to assign approvals directly to
individual users, you can also add all role-based external users
directly to queues and use the queue to assign approvals.
Communities: Let External Users Approve History
Related List on Records
BEFORE EDIT
AFTER EDIT

20. We gave the guidelines an informal trial run.
● We did a soft launch.
● Created some examples of model titles and shortdescs.
● Did ad hoc consultations with writers.
● Held title and shortdesc office hours.
● Evangelized on internal social media.
● Advocated for an end-to-end edit by a single editor.
20

21. Implementation challenges, and what we’d like to do next.
● Continue evangelizing the guidelines.
• Give positive reinforcement during every release kickoff.
• Increase compliance by working with release note wranglers in each product area.
• Reinforce good practices via the editing process.
• Communicate changes as the guidelines evolve.
● Train the doc managers.
● Train new hires.
● Maintain the library of examples.
21

22. Selected bibliography.
Art of the Short Description, Kristen James Eberlein, Systems Documentation Inc.
http://dita.xml.org/sites/dita.xml.org/files/art_of_the_short_description.pdf
Google Search Engine Optimization Starter Guide
http://static.googleusercontent.com/media/www.google.com/en/us/webmasters/docs/search-engine-
optimization-starter-guide.pdf
“Reflections on Writing Short Descriptions,” Tony Self, guest post on TechComm Central by
Adobe
http://blogs.adobe.com/techcomm/2013/06/reflections-on-writing-short-descriptions.html
Shortdesc Standard, Darwin Information Typing Architecture (DITA) Version 1.2
http://docs.oasis-open.org/dita/v1.2/os/spec/langref/shortdesc.html
Some DITA industry standards for titles and shortdescs.
22

23. Questions?
23
Cate de Heer
cdeheer@salesforce.com
Liane Yee
lyee@salesforce.com

24. thank y u
24