Herding Tigers: Letting Go of Inline Links


Published on

How we are learning to let go of inline links for the customer's good.

  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • How many attendees are authoring in XML? FrameMaker? What else? This problem intensifies with DITA, but it exists in other formats to a lesser extent.

    Links were my go-to architecture choice for fifteen years.
    Think a reader might be interested in a related topic? Put a link on it!
    What’s the harm?
    Speed and comprehension
    In a DITA environment, entanglement trouble
    If you put a link on it, you may miss better solutions to your customer’s problems
  • 22 of 3800 studied in our help.
  • CCMS trial performed badly because there were so many inline links that the content is well and truly entangled.

    Easy for a writer to make a mistake and hose another writer, or all of them, for 10 minutes to four days (my record).
  • This developer doc is worse than our worst help topic, but it illustrates the point nicely.

    This was my doc, and I thought this was good writing after fifteen years as a technical writer.

    I was wrong. We removed most of these links, never heard a word about them. They simply weren’t delivering value.
  • If there’s internet: https://help.salesforce.com/apex/HTViewHelpDoc?id=setting_up_email-to-case.htm&language=en_US
  • These are “books” that live together in help.salesforce.com.
  • Our UI sometimes forces us to talk about separate tasks in the same topic.

    And yet, if a link is really necessary—aren’t we saying that the content should be in that topic for 80% of the users? So shouldn’t we just put the content in the topic?
  • 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!
  • If you’re referring someone to another topic for just a bit of info, conref it in!
  • Writers who got to work with topics that truly had random, unnecessary, “just in case” links had fun. Some likened it to gardening or doing the dishes, very peaceful in our release-driven, guess-what-changed-now environment.
  • Writers who had put a lot of work into map topics that had to be dismantled were not happy. Writers who fight for the 1% were really unhappy.
  • It’s hard to see that when you stuff “what if” links into a topic, you’re making it harder for the other 90% of readers to get through the content.
  • Hard architecture problems required serious rethinking—but there wasn’t much time to do this.

    Show opp edit page:

  • Two topics, one without links, one with. What do the stats tell you after a year?
  • Two topics, one without links, one with. What do the stats tell you after a year?
  • Two topics, one without links, one with. What do the stats tell you after a year?
  • Herding Tigers: Letting Go of Inline Links

    1. 1. Herding Tigers Letting Go of Inline Links Mysti Berry Principal Technical Writer @MystiContent in/mystiberry
    2. 2. @MystiContent @SingleSourcing About the Speaker • Technical Writer for 2 decades • Content Strategist for 2 years • Currently on Internal Doc team
    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. Put a Link On It
    5. 5. Today We’ll Discuss • What’s wrong with inline links • What we did to remove unnecessary inline links • How the team responded • Best practices if you’re thinking of purging links
    6. 6. What’s Wrong with Inline Links?
    7. 7. What’s Wrong with Inline Links? • Links slow every reader slightly, and slightly decrease comprehension as measured by recall. • Links are clicked between 0%-8% of the time in our highest viewed, lowest rated topics. Maps get 20%-35% clickthrough at best. (More research needed) • The resource manager in some tools is painful, takes writers a few minutes per link to create. • Refactoring content that contains links is a nightmare. • If we rely on manual, inline links, we’re not looking for better solutions. Lesson: We’re spending time and money on resources that no one uses, resources that slow down every reader, and help very few.
    8. 8. How Bad Was It? • Our doc builds were slower because of inline links. • Many topics triggered a build of topics not in the ditamap because of entanglement. • More than a few circular references, unnecessarily disjointed topics. • Writers want to refactor content, but embedded links turn a four-hour task into a three-day job.
    9. 9. Example of Excessive Links
    10. 10. Scent of Information Grows Faint…
    11. 11. Scent of Information Grows Fainter Still… Wait…where am I?
    12. 12. If We Couldn’t Use Links, We Would Write This Better?
    13. 13. What We Did
    14. 14. What Did We Do? As part of a now-or-never re-architecture project, I asked writers to remove all inline links that crossed “bundle boundaries” in the help: • Learn Salesforce Basics • Set Up and Maintain Your Organization • Analyze Your Data • …. We removed 4300 inline links, or 46% of them. We have about 4,000 help topics.
    15. 15. Sounds Easy, But Not So Much… • We had hundreds of ditamaps, thousands of topics, and thousands of manual, inline links. • We had to evaluate each link in each topic. We hit user limits on Google docs just tracking things. • We had to choose: • Delete the link because it really wasn’t necessary. • Do something because the link really was necessary.
    16. 16. “Necessary XREFs” • Readers would suffer loss or corruption of data if they didn’t follow the link. • Readers couldn’t complete a task without the link. For example, some steps in a large task contain complex subtasks. If an XREF was within the top-level ditamap, it could stay. If it pointed to a topic outside that ditamap, we had to do something. Question: If an XREF is necessary, why isn’t the content?
    17. 17. Solutions 1 of 3: Get them back in the UI
    18. 18. Solutions 2 of 3: Conref instead of link Steps 3 and 4 contain information shared across several topics.
    19. 19. Solutions 3 of 3: Fix the Topic Depends on what’s wrong: • Can you send the user back to the UI? • Is it an overstuffed topic? • Are we focusing on the customer’s path through the product? There was very little time for real refactoring/redesign of topics in our project. We didn’t do enough analysis of the problem topics.
    20. 20. How The Team Responded
    21. 21. Some content creators LOVE to delete stuff
    22. 22. Some content creators HATE to delete stuff
    23. 23. It’s Hard to Let Go of Links • My team of brilliant and empathetic writers want to help every customer. It’s hard to see that sometimes helping the few (0-8%) actually makes it harder for the 90%. • Our Information Model encourages small topics, so a link seems like the right solution, especially under time pressure. • We have tasks that span features, so writing doc is like when you fix your sink and then have to run to the hardware store. That’s hard to do without links.
    24. 24. We Didn’t Find All the Answers • Features start out as isolated, become app-wide service. How can we revise the basic structure of docs as product and feature definitions change frequently? • We require help link on every UI page. But customers aren’t clicking some of those links. What do you do?
    25. 25. I Failed To Persuade the Tigers • One hack day project recently discovered that in our most viewed, most disliked topics, customers click links 8% of the time or less. But this hasn’t generated any new enthusiasm for deleting links in favor of content. • There’s a movement to use DITA chunking to article-ize small topics together in one HTML output—which for some content may be a great idea! If overused…? • Some writers are truly frustrated with the link limitation.
    26. 26. We’re Still Not Looking for Better Structure • “It’s been hard to hear from my cube…that these topics are awful. I put an entire release into taking those topics from 5 page scrolling walls of text into concise, complete map topics, and all of that effort was quickly undone in [the work to remove inline links].” • “…we heard from a few users in our usability sessions that in task-of-task topics, seeing steps that are simply statements of what needs to be done without links to the relevant topics can be confusing.”
    27. 27. Some Writers Have Put Links Back! This is an often-visited, low-rated topic with many customer comments. What could the writer have done aside from add the links back in?
    28. 28. Do Links Address These Comments? • not helpful I want to delete an opportunity - ? how? • i need to arrange the group based on close date or stage, etc. I am looking for the definition of closed date on the opertunity screen. i found no useful information on this question here. • does not tell me how to do any of the items from the error report! • Was trying to see if you could actually sort the various Opportunities columns by Opportunity Name. Above comments weren't very relevant.
    29. 29. Best Practices for Purging Unnecessary Links
    30. 30. Why Bother? • You need to COPE (create once, publish everywhere). • You can’t COPE with entangled content. • Downstream processes break with too many inline links. • You have to do a lot of manual work for every new combination. • Refactoring existing content takes 10 times as long as it should. • Because mobile…
    31. 31. You Can’t Herd a Tiger (or a writer)
    32. 32. But They’re Fierce Customer Advocates So just make it easy, and clear why it’s a good thing: • Check your metrics before proposing style or guideline changes. Try some experiments first. • You can’t say this too many times: “We were making the best guesses we could. Now we have more information. It’s not you. The requirements have changed.” • You must give writers alternatives like “get them back to the UI as quickly as possible” or “move that to a resource file and conref it in,” and then make it easy.
    33. 33. Invest in Project Management • A manager spent a lot of time organizing us by spreadsheet, auditing our content to size the project, and running agile-style meetings to keep us moving. • Analyze the thorny problems before you begin. • Attack a small hunk of content at a time. We couldn’t, as most of the topics were so entangled with each other. • Try writing a new doc in the new style and sharing metrics with writers first.
    34. 34. If You Aren’t in XML/DITA Yet • Get rid of links before you convert from FrameMaker. • Make your content as structured as possible before you convert. • Don’t go crazy with reuse. Establish guidelines so you don’t become entangled. Most important guideline for help: don’t publish reused material (keep it in resource files). Doesn’t always work for reference documentation.
    35. 35. Mysti Berry Principal Technical Writer