Reuse Strategies to Support the 
API-ification of Your Content 
First Steps 
Mysti Berry 
Principal Content Strategist 
@M...
@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 
cont...
Today let’s discuss 
• What I mean by “API-ifying your content,” and why it’s 
important 
• How API-ification can save you...
Caveat 
I don’t have all the answers, especially the technical ones. 
I do know that entangled 
content stops even the 
be...
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 c...
With an API layer, your content is everywhere! 
Code 
complete 
in text 
editors, 
IDE, UI 
forms 
Rollover 
hints in 
UI,...
Why API-ify? 
• We used to write books. Handy for scoping by 
audience. 
• Then we wrote helpsets. Hey, isn’t search GREAT...
Why API-ify? Because future! 
Not just a device proliferation issue, which DITA handles. 
Social media changed customer ex...
Why API-ify? Because customers! 
Do your customers: 
• Simultaneously complain about too much and not 
enough information?...
Why API-ify? Because experts! 
Content strategy empresaria Karen McGrane tells the NPR 
story very convincingly. 
Credit: ...
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 ...
How can API-ification earn money? 
• Charge customers for content integration. 
• Great content closes sales. 
• Great con...
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: im...
Removing Roadblocks
Required: disentangle reuse 
What we did: as part of a now-or-never re-architecture 
project, writers removed all inline l...
Figure out a better navigation than XREFs 
• Inline links may be a patch—fix the problem and the 
need for the entangling ...
Solutions 1 of 4: get them back in the UI 
• Instead of: 
<xref>Enable Email-to-Case and configure your 
Email-to-Case set...
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 ...
Solution 4 of 4 Page 2: Use DITA smarter 
• We have a Limits & Limitations guide, which we had to 
create manually, becaus...
Removing roadblocks: summary 
• Get reader back in the UI, not off to another topic. 
• CONREF instead of XREF. 
• Fix the...
Next Steps to Content API
After removing roadblocks, build it! 
API-ification = single-sourcing ++ 
• Predictable structure within topics 
Consisten...
Mysti Berry 
Principal Content Strategist
Reuse strategies to get you ready for a Doc API
Upcoming SlideShare
Loading in …5
×

Reuse strategies to get you ready for a Doc API

372 views

Published on

Karen McGrane's call for us all to create once and publish everywhere assumes that we all have a Doc API like NPR's. We don't, but as we work toward that, we can look at reuse strategies to make the transition easier.

0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
372
On SlideShare
0
From Embeds
0
Number of Embeds
5
Actions
Shares
0
Downloads
5
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide
  • Not to mention API-ification!
  • There is much joy because we spend more time creating, curating content, not rewriting it!
  • “because” became a preposition in about three months. We’re living through similar swift-changing times.
  • Ask audience to tell attrition stories if they can. Do their sales groups use content to close sales? Can they charge for content integration?
  • How can the Magic API elves parse these two topics?
  • What happens when I make a version of the product that leaves out lines 2, 7-10? What about when in the course of a sprint we add six features and then pull them back at the last minute? These are hand-crafted lists. It’s what we thought customers wanted, but the metrics say, not so much.
  • These are “books” that live together in help.salesforce.com.
    Ask audience—what’s your inline linking strategy?
  • Writers loved this—except that it means more maintenance when click paths change (resource files help that).
  • If you’re referring someone to another topic for just a bit of info, conref it in!
  • What should the help for this landing page be?
  • How would you fix this? We used shortdescs and linking to generate parent navigation topics. But if someone is just learning about something, do they want a list of everything they can do? Or do they want one clear next step?
  • Ask audience to share other tools, especialy keys.
  • Ask audience to share other tools, especialy keys.
  • Reuse strategies to get you ready for a Doc API

    1. 1. Reuse Strategies to Support the API-ification of Your Content First Steps Mysti Berry Principal Content Strategist @MystiContent in/mystiberry
    2. 2. @MystiContent • Technical Writer for 20 years • Content Strategist for 3 years • Big DITA fan
    3. 3. 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.
    4. 4. 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
    5. 5. 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.
    6. 6. What Do You Mean, API-ify?
    7. 7. 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!
    8. 8. With an API layer, your content is everywhere! Code complete in text editors, IDE, UI forms Rollover hints in UI, doc, training, internal code Content API Layer Content response to customer behavior in form factors Integrate with customer content “Show me” interactivity Mobile overlay Labels Video Content in small topics, with associated metadata
    9. 9. Why API-ify? • We used to write books. Handy for scoping by audience. • Then we wrote helpsets. Hey, isn’t search GREAT? • Now?
    10. 10. 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!
    11. 11. 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.)
    12. 12. 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
    13. 13. How API-ification Can Save and Earn Money
    14. 14. 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
    15. 15. How can API-ification earn money? • Charge customers for content integration. • Great content closes sales. • Great content prevents attrition.
    16. 16. Roadblocks in the Content
    17. 17. Content isn’t consistent Machines can’t parse snowflakes
    18. 18. Content isn’t modular
    19. 19. 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.
    20. 20. Removing Roadblocks
    21. 21. 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.
    22. 22. 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)
    23. 23. 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>
    24. 24. Solutions 2 of 4: CONREF instead of link VS
    25. 25. Solutions 3 of 4: Fix the real problem
    26. 26. Do readers want a million paths, or one?
    27. 27. 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:
    28. 28. 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!
    29. 29. 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.
    30. 30. Next Steps to Content API
    31. 31. 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!!!!!
    32. 32. Mysti Berry Principal Content Strategist

    ×