Reuse strategies to get you ready for a Doc API
-
Upload
mysti-berry -
Category
Documents
-
view
122 -
download
3
description
Transcript of Reuse strategies to get you ready for a Doc API
Reuse Strategies to Support the API-ification of Your ContentFirst Steps
Mysti BerryPrincipal Content Strategist
@MystiContent
in/mystiberry
@MystiContent
• Technical Writer for 20 years
• Content Strategist for 3 years
• Big DITA fan
Safe Harbor
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 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, 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, risks associated with 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 ended January 31, 2011. This document and others 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 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.
Today let’s discuss
• What I mean by “API-ifying your content,” and why it’s
important
• How API-ification can save your company money and
earn your company money
• Roadblocks to API-ification
• First steps to remove roadblocks and prepare content,
using examples from our work at salesforce.com
Caveat
I don’t have all the answers, especially the technical ones.
I do know that entangled content stops even the best solutions, like DITA, from exploiting content assets for new form factors, content combinations, and locations.
What Do You Mean, API-ify?
What does API-ify mean?
Storing your content in small enough units, with predictable
internal structures, so a machine can grab any combination
and pump it out to a new delivery channel without writer
intervention.
API-ification requires:
• Predictable structure within topics
• Well-defined taxonomy/subject scheme/metadata
• Magic API elves to pump that content to multiple
destinations in limitless variation. Without error!
With an API layer, your content is everywhere!
Content in small topics, with associated metadata
Content API Layer
Content
response
to
customer
behavior in
all form
factors
Code
complete
in text
editors,
IDE, UI
forms
Rollover
hints in
UI, doc,
training,
internal
code
Integrate with
customer
content
“Show me”
interactivity
Labels
Video
Mobile
overlay
Why API-ify?
• We used to write books. Handy for scoping by audience.
• Then we wrote helpsets. Hey, isn’t search GREAT?
• Now?
Why API-ify? Because future!
Not just a device proliferation issue, which DITA handles.
Social media changed customer expectations• Just what I need to know
• Just when I need to know it
• Preferably, show me before I need to know
However, “psychic” is not in our skill set!
Why API-ify? Because customers!
Do your customers:
• Simultaneously complain about too much and not
enough information? They aren’t crazy.
• Ask for open source docs so they can roll their own?
• Turn to third parties to explain your products to their
customers?
(No customer feedback? Getting it is Step Zero.)
Why API-ify? Because experts!
Content strategy empresaria Karen McGrane tells the NPR
story very convincingly.
Credit: http://mfglabs.com/charles-darwin-and-apis/ For more: Karen McGrane & NPR
How API-ification Can Save and Earn Money
How can API-ification save money?
• Lowered support costs: gold-file quality content prevents
calls. Especially if it’s in the app, not in an HTML silo.
• Lots of labor savings, because content is created once,
never refactored.
Technical documentation groups are great at creating
accurate content. If it’s reused, not rewritten, it stays right.
#TechPubsGetsCuration
How can API-ification earn money?
• Charge customers for content integration.
• Great content closes sales.
• Great content prevents attrition.
Roadblocks in the Content
Content isn’t consistent
Machines can’t parse snowflakes
Content isn’t modular
Content lacks external metadata
• Why external to the topic? It’s easy to overload topics
with metadata requirements: imagine 30 values times
10 different qualities you want to capture. Plus filtering.
• It’s also hard to go in to each topic and change values
when the metadata changes or a new value is added.
Note: We’re experimenting with subject schemes to
automate mechanical tasks and show ways to dynamically
deliver content.
Removing Roadblocks
Required: disentangle reuse
What we did: as part of a now-or-never re-architecture
project, writers removed all inline links that crossed
“bundle boundaries” in the help. We can now publish
parts:• Learn Salesforce Basics
• Set Up and Maintain Your Organization
• Analyze Your Data
• ….
We removed 4300 inline links, or 46% of them. We had
about 4,000 help topics.
Figure out a better navigation than XREFs
• Inline links may be a patch—fix the problem and the
need for the entangling link goes away:• Point reader to the right place in the UI, not to a help topic.
• If content really needs to be there, CONREF it in from a
resource file, don’t link to it.
• Fix the architecture so you don’t need the link. (Difficult)
• You may be hand-coding stuff that DITA can provide
(<shortdesc> + linking=“normal” is *easy*; keys)
Solutions 1 of 4: get them back in the UI
• Instead of:
<xref>Enable Email-to-Case and configure your
Email-to-Case settings.</xref>
Solutions 2 of 4: CONREF instead of link
VS
Solutions 3 of 4: Fix the real problem
Do readers want a million paths, or one?
Solution 4 of 4: Use DITA smarter
• Example: Auto-generate container navigation topics.
• Example: Use keys to simplify filtering.
• Example: Experiment with subject schemes to generate:
Solution 4 of 4 Page 2: Use DITA smarter
• We have a Limits & Limitations guide, which we had to
create manually, because:• No consistent metadata (external or internal), so machine can’t
find all the limits and limitation topics.
• No consistent internal structure, so machine can’t pull out the
limits and limitations from topics with other content.
Without these roadblocks, we’d have an automatically-
created resource instead of burdening writers with
“remember the limits guide!” I want the future, now!
Removing roadblocks: summary
• Get reader back in the UI, not off to another topic.
• CONREF instead of XREF.
• Fix the real problem.
• Use DITA smarter.
Biggest lesson: we can guess, but we should test our
guesses with metrics. Try something new in a troubled
topic, see if you can improve pageviews/satisfaction.
Next Steps to Content API
After removing roadblocks, build it!
API-ification = single-sourcing ++
• Predictable structure within topics
Consistency like you get with forms-based authoring!
• Well-defined taxonomy/subject scheme/metadata
We’re experimenting with subject schemes. What else?
• Magic API elves to pump that content to multiple
destinations in limitless variation. Without error!
You need developers, QA, product manager—you’re really
building a product that you can sell.
Please please stay in touch! The future is so close!!!!!
Mysti BerryPrincipal Content Strategist