Your SlideShare is downloading. ×
Berry weeds cidm_2012
Upcoming SlideShare
Loading in...5

Thanks for flagging this SlideShare!

Oops! An error has occurred.


Introducing the official SlideShare app

Stunning, full-screen experience for iPhone and Android

Text the download link to your phone

Standard text messaging rates apply

Berry weeds cidm_2012


Published on

  • Be the first to comment

  • Be the first to like this

No Downloads
Total Views
On Slideshare
From Embeds
Number of Embeds
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

No notes for slide
  • Abstract: developed a formal Information Model several years after converting from FrameMaker to DITA. The writing team has struggled to understand how specialized topics work, and how to implement them with existing generic topics that often lacked structure. Ad hoc content references inhibited our ability to update existing topics.
    We employed a content strategist to redeploy the Information Model. Technical communications groups typically perform content strategy without the help of a specialist, but the demands of rapid growth, Agile development, and weekly deployments required a dedicated resource to:
    - Identify content issues disguised as tools or organizational problems
    Facilitate communication between highly-skeptical writers and the overburdened tools team
    Implement solutions that take full advantage of DITA's strengths
  • Moving from unstructured to generic topics is a common strategy. Our portals were help & training window in the app, and a public-facing server for dev doc.
  • Choosing Object Relationships first bullet is a task! The second bullet is tightly bound in a way the bullets aren’t in the first section. If there’s wifi:
    Our brave Analytics writers are tackling this topic as we speak!
  • Explain English-Only problems. # 3 is filtering issue—repeated content to avoid breakage.
  • Unforeseen problems: task has a lot of unique elements. Conrefs to/from quite difficult when 80% of your content is in <topic>
    More about the epic battle in a minute!
  • Everyone on the Info Model team assumed writers would all embrace structured writing—but by the time of the rollout, over half of them had never had the training. Structured writing is very different from unstructured, challenges you to ask harder questions than when you just “doc the UI.” Also, many writers believe in the myth of three click limit.
  • Nearly 10,000 topics, less than 300 have shortdesc. We ended up with: You need access and appropriate permissions to completethe code example.
  • What about my customers, call center folks. They need answers now! From the one page of context sensitive help! I have to dump it all there!
    DITA can give the illusion of structure.
  • Abandoned things include: taxonomies for search in our own doc portal (had to align with Knowledge Base), SEO concerns, how do we fix generic topics? Care and feeding of Info Model—who makes sure needed changes are implemented? Who measure success and provides support to struggling writers.
  • Style question: when do we use <shortdesc>? Info Model answer (encoded in style guide): when it’s not clear “why” from the title.
    Success stories: Pavi & ISVforce, Ted and omniture, people want to do smart things, fix hard problems
  • Transcript

    • 1. Climbing Out of the Weeds: Moving from Generic to Specialized Topics Mysti Berry Principal Content Strategist @MystiContent mystiberry
    • 2. We Started with a Lovely Garden Plan  Before DITA: – FrameMaker books for Help, API Guide, a few miscellaneous things – Topic type = chapter or long topics (busy UI pages)  After DITA: – About 2,000 XML files (Perforce is our CMS) – Writers never have to make the same change by hand in different branches. – Reuse even easier than with FrameMaker – Topic type = <topic> – 10 writers, two portals, 90% non-overlapping topics
    • 3. To be honest, there were weeds from Day One  Massive ad-hoc reuse = ticking time bomb  Information types mixed up in single topic files  Nested topics in a single file I’ll always regret saying, “Oh, that’s going to take forever to untangle. Let’s just convert as is, and fix it later.” For example…
    • 4. Is this structured? Is it all concept? All reference? Hidden tasks?
    • 5. Reuse is hard: Ad hoc conref “English Only” mismatches Filtering
    • 6. Weeds Choked the Garden  Some writers spent hours diagnosing content issues that caused build failures.***  Writers had to choose between not reusing content, or spending hours or days refactoring mixed content.  Ad hoc conrefs made reuse hard. ***We have weekly and quarterly publishing cycles, three branches, continuous auto-integration. We’re fanatical about checking in “clean code.”
    • 7. No Hay Problema – Enter The Info Model Team!  Whole team trained in Information Model by Ms. Hackos  Team led by our Information Architect Steve Anderson  Development done “in our spare time”  Invited volunteers staffed the team  We have a culture of innovation, a long habit of spinning up SWAT teams, and an Agile mindset. What could go wrong?
    • 8. Results  Over a year later, we had an Information Model! – Topic type definitions and guidelines: <task>, <reference>, <concept>; <topic> only if desperate – Deliverable type definitions and guidelines – Patterns – Templates  Trained writers on how, but the “why” was hard to grasp  We didn’t require they use new topic types  Didn’t restructure existing generic topics: $$L10N$$ limits
    • 9. Information Model Flopped (a bit)  Incomplete before we could publish it (adding new deliverable types all the time)  Writers struggled to reuse existing, unstructured content  Despite templates, writers gave up quickly when: – Asked to create many more files than they used to – Asked to write in a highly structured way—epic <shortdesc> battle – Faced with “task can’t conref into generic topic” problems – A few issues w/templates and unforeseen problems: task  Some managers encouraged writers to ignore new model
    • 10. Another year later and…  2,000 topics had become 5,000 topics  30 writers—less than a third of us had the full training  Three document portals, some with shared, filtered content  Doc Tools team challenged by high demands (More portals! More deliverable types! Support more writers!)  Some writers believe in the myth of three clicks  Our architecture reinforced “documenting the architecture, not the user goal.”
    • 11. Did I mention, structured writing is really hard?  Your turn: create a compelling <shortdesc> – Topic title: Prerequisites for Fooing a Bar – Body: a list of the prerequisites, no intro <p>. Prerequisites are for being able to use the quick-start code in the first chapter of a developer guide for FooBar. – Does this need a <shortdesc>? Does the title answer both ‘what does this topic tell me’ and ‘why do I need to know it’?
    • 12. To sum up:  We had a lot of content problems blocking specialization.  Writers were unconvinced that they needed to write in a more structured way. They didn’t believe little tiny topics add up to customer satisfaction.  The Info Model Team needed to roll over to other duties.  Meanwhile, two team members attended a Content Strategy conference (Confab), and managers heard a lot about it at conferences like this one.
    • 13. Hey, Let’s Get a Content Strategist!  We had two (now three) dedicated full-time resources on build processes and tools, but no one focusing on content at the global level  Tech Pubs teams typically do content strategy as part of our day jobs: but some things are left abandoned in a fast-growing group  Finding content strategists with enterprise-class tech pubs experience (much less cloud experience) was challenging, so we finally hired from within
    • 14. Tweaking the Information Model
    • 15. Add One Full-time Content Strategist  Owns a backlog of issues – writers have someone to listen to them, to track issues, and advocate to resolve content issues  Guides doc efforts aimed at existing unstructured content: audits and advice  Can focus on repairing information model – Fix broken or missing elements – Reintroduce info model to team – Fill in belief gaps
    • 16. Started with lots of goodwill  I’d been a writer for 20 years, at Salesforce for five years. Team knew I knew the challenges  Worked on the API doc, which meant working with nearly every other writer on the team at some point  I’d been hollering “we need a good content strategy” for at least a year—whether or not I knew what that meant!  High visibility from successful projects, lots of goodwill
    • 17. Repair work  Presented intentions to the whole team – Info Model is here to stay – 3-click limit is a myth – Not everyone believed me at first (huh!) – Director confirmed “Info Model no longer optional”  Fixed issues with templates  Added missing deliverable types  Interviewed all 45 writers to ask about their concerns— turned the common themes into my backlog
    • 18. More repair work  Invited anyone interested to join new Info Model Team – Goal: provide coverage, person-hours to do the work – Spread knowledge and skills across team  United Style team and Info Model Team – Bugs against style guide sometimes require Info Model weigh-in – Common goals to create easy-to-reuse, consistent content  Added office hours for Info Model questions – Work with writers 1:1 to clarify subtle issues of structured writing —success breeds enthusiasm – Coach writers on “follow the user’s path” not “doc the feature”
    • 19. More repair work  Created videos for writers’ pain points – Easy way to create lots of topics, add them to ditamap – How to use task topics (reuse content in multiple deliverables)  Consulted with teams set to tackle “legacy issues” – Ensure audit efforts are focused & productive – Deliver guidelines for what to tackle, publish to rest of team – The team taught me what to do: set their priorities, scoped what they could do, made a backlog
    • 20. Start Liaison Work with Rest of Company  Joint projects with Support – Support and help topics in same repository, require a single taxonomy – Ongoing maintenance of taxonomy  “Customers for Life,” Other Initiatives – Some marketing folks interested in Content Strategy – Training, many other functional groups generate content for customers—resolving terminology clashes, look-and-feel issues, etc. challenging without a dedicated role
    • 21. How Successful Are We?
    • 22. Are Things Better?  We’ve gone from about 10% of new topics being specialized to about 95%  Writers are asking more “how do I” and less “why do I have to” questions  Teams are tackling hard problems like how to go from ad hoc reuse to resource files  Other teams reaching out to doc more because they have a single point of contact
    • 23. Lessons Learned  Don’t wait to fix structure issues  Don’t wait too long to go from <topic> to specialized!  Structured writing is harder than unstructured  Some writers need convincing that short topics are good  Whether or not the person is titled Content Strategist, dedicate someone to curate content in big company  Include the writers at every stage: they know where the bodies are buried