berry 10 years_of_dita
TRANSCRIPT
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 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.
Safe Harbor
Agenda
Why DITA in 2005?
What Went Right
A Few Wrong Turns
Where Do We Go From Here?
Where Do You Want To Go?
Agenda
Why DITA in 2005?
Continuous integration needed
(not batch & merge)
Multiple authors in the same BLOB files
Localization needs:
Hard to find what had changed from last release
Lots of other issues I can’t remember
FrameMaker Wasn’t Meeting Our Needs
Continuous Integration
3 release branches.
3 staging branches per release branch.
Plus special feature branches.
Many writers edit the same files. So we need continuous integration in the same branch, as well as continuous integration from branch to branch. Dozens of writers in some files.
Supports Agile goal of being ready to publish what you check in.
Localization
Fully support 18 languages, partial support of 17 additional languages.
We need to measure deltas in the source: changes that affect localization costs.
We need support for our translation memory.
XML/DITA: Power, Flexibility, Consistency, MetricsTo support our lean, fast, cost-efficient localization and publishing
What We Did Right
Guidelines
Writers followed the style guide, understood why consistency is important.
Writers followed directory and file name conventions (no CCMS).
Prep
Tackled the most rambling topics to make them topic-based before porting.
We had a secret weapon, the best Doc Tools team ever. Steve wrote lots of scripts to save writers doing rote tasks as much as possible.
What We Did Right: Prep and Guidelines
Implementation
Converted documentation a few deliverables at a time, so we could learn lessons and improve process.
We had a secret weapon, the best Doc Tools team ever. Steve wrote lots of scripts to save writers doing rote tasks as much as possible. If a script didn’t work, throw out the results, tweak the script, and run it again! Free to experiment this way.
Results
Localization costs don’t spiral out of control (so many languages! Changes to style!), Loccan get a “diff” whenever they need to.
Very efficient translation memory.
Made large architectural changes on short notice (database.com, break-up-the-guide, Trailhead, new portals for existing content).
What We Did Right: Implementation and Results
A Few Wrong Turns
Wrong Turn #1: Reuse Issues
Using Source Files Instead Of Resource Files
Using Way Too Much Ad hoc Linking
Linking to Partial Units
Reuse Issue: Using Source Files Instead Of Resource Files
Text is used in multiple places.
It’s defined in a published topic, not a resource file.
What happens if you want to change or reorganize this content?
Reuse Issue: Using Way Too Much Ad Hoc LinkingIf you put a link on it, you don’t look for any better solution.
Unstructured complexity: why is my doc broken?
Weak scent of information.
Customers don’t use most links!
Reuse Issue: Linking To Partial Units Of Information
Easy to create word salad.
Hard for writers to understand and maintain.
DITA filtering != FrameMakerconditional text. Seriously…
<title>
<ph id="topic-title">
<ph platform="API">c</ph><ph platform="OT">C</ph> reate</ph></title>
To get “create” for SOAP API, “Create” for
Office Toolkit.
Filtering
1. We had to use subtractive filtering AND either/or filtering.
2. We had orthogonal filters (platform, product group, language): logic is hard to keep in your head.
3. Filtering on incomplete units leads to word salad, often without the writer knowing it’s happened.
4. Tagging is in the topic, so changes require huge effort.
5. Mobile amplified problems.
Wrong Turn #2: Our Approach To FilteringIn-topic filtering doesn’t scale.
Filtering UI:
The writer has to know the whole doc set to tag for filtering.
Filtering Example: Mobile
Hard to change location of resource file, as it’s expressed in EVERY CONREF.
Writer has to look at all the content for all the platforms/flavors (though I think we have filtered views for Oxygen, or should have soon).
Writers and content architects have to know the structure of the content inside and out to build the right files.
Easy to break accidentally.
Good outcome of all the content dependent on iron-clad discipline of all the writers.
Everything in the source file:
<!--iOS and Android Help-->
<p mobileweb="No" consolidatedmobile="No">
<ph conref="../../help/resource
/salesforce1/salesforce1.xml#salesforce1/sf1_
data_supported_today_hybrid_phone"/></p>
<!--S1 User Guide-->
<p consolidatedmobile="Only"><ph conref=
"../../help/resource/salesforce1/salesforce1.
xml#salesforce1/sf1_data_supported_today_core
_help"/></p>
Where Do We Go From Here?
For localization, use Acrolinx for word-level control, random sentences that should be the same.(Doing now, full support from everyone everywhere.)
As we write new content and replace old content, favor conkeyrefs over filtering.(Brave writers testing the waters—any writer currently filtering wants to stop filtering)
Create reuse guidelines for writers: don’t reuse partial units, use resource files, stop ad hoc, inline links. (We’re working to get alignment, especially with links.)
DITA isn’t meant to do EVERYTHING
Lesson #1: Use The Right Tool For The Right Job
Most of all, think about content as something you manufacture, for a wide variety of unknown deliverables. Stop thinking in terms of books. (It’s not that easy!)
Let someone else manage the look-and-feel. Stop hand-crafting content, because, trust me, you never know where it’s going next!
DITA can send your content anywhere!
Always easier to change ditamaps than published content
Lesson #2: Do It In The Ditamap
Conkeyrefs
“Keys” are like variables.
You define the value for each variable in a file that isn’t published.
In the ditamap, you say “for values of variables, look here.”
In the published file, you “point” to the content you want with the variable, and the ditamap knows which value to fetch.
More About ConKeyrefsMore flexible than filtering
output output
Keyref example (conkeyref)
Flexible: add, rearrange, combine in new ways—all you have to do is edit resource files that are never published, and ditamaps. No asking “how does this affect existing content?”
Easy for writers to read: she only sees “her” values.
Variable in source file:
<p>You, the Client: <ph
conkeyref="proposalinfo/client">
Client Name</ph> are responsible…
Ditamap says where to look for “proposalinfo”:
<keydef keys="proposalinfo"
href="proposalinfo.xml"
type="topic" format="dita"/>
Resource file holds definition of “client”:
<ph id="client">XYZ</ph>
A Brief Word About Our Authoring Tool
We used Arbortext Editor for 9 years, and hated the last four.
We switched to Oxygen:-- Looks “codey” but very flexible, we can make it do just what we need.-- Great search capabilities, especially searching within resource files.-- Since we deliver in so many formats, WYSYWIG loses meaning.
Where Do You Want To Go?
Dream Big!
Where do you want to go with DITA?
What’s holding you back?
Thank you
Mysti Berry, Principal Technical Writer
@MystiContent