Analyzing Your Deliverables: Developing the Optimal Documentation Library


Published on

Presented Nicki Bleiel at Documentation and Training Life Sciences, June 23-26, 2008 in Indianapolis.

Documentation deliverables have evolved beyond manuals and online help in recent years, and with the emergence of Web 2.0, things are changing faster than ever. Technical communicators have many more options to enhance the user experience, and developing many of them provide the opportunity to work with other departments to find a more holistic approach to content development and delivery. But there is no one-size-fits-all set of solutions. This workshop will review the types of analysis you need to do to determine which deliverables are right for your project, your customer, and your company. Product analysis, user expectations and needs, internal needs, deliverable options, and optimizing your library will all be discussed; as well as translation needs, staff/time constraints, file size limitations, corporate image and control, and proprietary concerns.

Published in: Technology, Education
  • Be the first to comment

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

No notes for slide

Analyzing Your Deliverables: Developing the Optimal Documentation Library

  1. 1. Analyzing Your Deliverables: Developing th Optimal D l i the O ti l Documentation Library (in a Web 2.0 World) Nicky Bl i l Ni k Bleiel Senior Information Developer ComponentOne DocTrain Life Sciences 2008 Indianapolis, IN June 26, 2008
  2. 2. What we ll discuss we’ll • Analysis y • Deliverables • Traditional • Web 2.0 • Putting it all together • What’s on the horizon? What s
  3. 3. Bottom Line What it’s all about … • Giving customers what they need •Bl Balancing customer needs and company needs i d d d • Driving the deliverables
  5. 5. Product Analysis y • How is the product delivered? p • What is your software development process? • What are the current library deliverables?
  6. 6. User Wants and Needs Your • How they work audience • Where they work • Skill level • Preferences
  7. 7. User Wants and Needs How to find • Interview out – Customer Support – Q/A – Training – Power Users • Read customer forum • Site visits • Surveys
  8. 8. Company Needs Your • Corporate Expectations audience • Corporate Image • Corporate Philosophy • Proprietary Concerns • Regulatory Concerns
  9. 9. Company Needs How to find • Talk to out – Product Mgmt. – Marketing • Look at Intranet – Blueprints – Road Maps – Requirements q • Don’t forget IT
  10. 10. Knowledge Management and Reuse • Investigate – discover sources of information • Find out what can be reused and shared • Let others know what you have available • Drive knowledge management • Encourage consistency
  12. 12. User Assistance Matrix • Matrix that covers all deliverables we will discuss. Includes: • Deliverable • Explanation/Details El ti /D t il • Features • Things to think about • Will reference as we go along g g
  13. 13. Popular UA Technologies Source: 2007 WritersUA Skills and Technologies Survey h07/skillstech_techs.htm
  14. 14. The Traditional Characteristics • Comprehensive • Controlled • Defined Organization/Structure • Taxonomy • Content Authors – One to Many
  15. 15. The Traditional • Manuals • Online Help • Embedded Help p
  16. 16. Brief History/Future of Online Help y p • 1988: QuickHelp p • Help for MS-DOS; Helpmake.exe • No HATs • 1990: WinHelp • RTF/Microsoft Help Compiler • Si l Single-sourcing b i born; fi t HAT released first HATs l d • 1997: HTML Help • Microsoft HTML Help Workshop released • HTML Help the new standard/Browser-based Help introduced
  17. 17. Brief History/Future of Online Help y • 2001 • Help 2.0 engine released, but only for integration with Microsoft Visual Studio. • 2003 • Announcement that Help 2.0 will not be released as a platform; Longhorn Help may be released in future future. • 2005 • Security fix affects .chm files on a network. • Announcement that Vista Help engine (formerly Longhorn Help) will not be released. Now named AP Help (Assistance Platform) Platform).
  18. 18. Brief History/Future of Online Help Notable facts about AP Help (originally announced 2003): • Uses XML (AML) markup • The “Assistance Escalation Path Assistance Path” Well designed UI A it Assistance Di Directly i UI tl in Help Pane and Help Center User Community y Your Product Support Center What s What’s next?? Update on new Help initiatives. initiatives
  19. 19. The Traditional • Job Aids • Websites /Intranets • Knowledgebases g
  20. 20. Traditional/Web 2.0 Transitional • Customer Forums • Demonstration Videos
  22. 22. Web 2.0 — Descriptions “Harnessing collective intelligence” g g — Tim O’Reilly, O’Reilly Media “The living web” “The active web” “The read/write web” —Jimmy Wales, Founder of Wikipedia
  23. 23. Web 2.0 Characteristics • Not Comprehensive • Not Controlled • Organic Organization/Structure • Folksonomy • Content Users – Many to M M t Many • “Crowdsourcing”
  24. 24. Web 2.0 Includes: • Wikis • Podcasts • Blogs • Widgets/Gadgets g g • Social Networks … and combinations of all the above
  25. 25. Web 2.0 20 Not everyone contributes equally – y q y • Creators (18%) • Critics (25%) ( ) • Spectators (48%) But all are important. p From Groundswell: Winning in a World Transformed by Social Technologies by Li and Bernoff
  26. 26. Wikis Websites that can be edited by anyone • Allow synchronous collaboration • Great for building Communities of Practice (COPs) ( ) • Keeper of the “Group Memory” •EExcellent for internal ll t f i t l knowledge management
  27. 27. EXAMPLES
  28. 28. Wikis Wiki drawbacks • Learning curve • Maliciousness • Adoption For those who prefer it, Twiki is a structured Wiki. See for list of wiki tools
  29. 29. Podcasts Downloadable audio files • Informal; can be very useful for certain audiences • Very easy to create/inexpensive y y p • Can be used to deliver training • Can post to iTunes (Technology: Software How To category) as free downloads. • Keywords in podcast title will increase findability findability.
  30. 30. EXAMPLES
  31. 31. Podcasts Challenges g • May not work for your audience • Generating material frequently g q y • Gathering talent
  32. 32. Blogs Originally “weblogs” or online g y g diaries • Can increase Search Engine Optimization O ti i ti (SEO) for your f company/ product • Can be used to promote/educate Blog & Comments = a customers about product features Conversation. Listening required. • Management can blog to employees l Have something to say… be ready for feedback.
  33. 33. EXAMPLES
  34. 34. Widgets/Gadgets g g Mini-apps pp • Updated weather, etc. • Used on webpages/social networking profiles • Can be used to broadcast any information
  35. 35. EXAMPLES
  36. 36. Social Networks Interactive communities that share interests/information The usual suspects: •,, News b k N bookmarking: ki •,,, Website bookmarking: •, Blog bookmarking: • Th ti
  37. 37. EXAMPLES
  38. 38. Social Networks Let’s look at some trends/statistics… trends/statistics • What’s in it for your y company? • What is the audience a dience interested in?
  39. 39. RSS Feeds RSS Feeds drive Web 2.0 • Really Simple Syndication • Makes it possible for users to receive a notice every time information is updated. • RSS Aggregators gather feeds and make information easier to keep track of. - Google Reader - Bloglines • Makes Web 2.0 a “push” rather than a “pull” system pull system.
  40. 40. MATRIX REVIEW: WEB 2.0 20
  41. 41. Incorporating Web 2.0 with Traditional •IIssues • Pitfalls • GAINS ( (can b substantial) be b i l)
  42. 42. Web 3.0 What is it? Many definitions • Th “Semantic Web” The “S ti W b” ― Tim Berners-Lee, inventor of the World Wide Web One definition you will like…
  44. 44. Best Practices • Analyze often • Know your audience • Keep up with trends • Tie Traditional/Web 2.0 efforts together Traditional • Single Sourcing • St t i Information Structuring I f ti • Continuous Publishing Web 2.0 • Encourage Communities of Practice • Explore non-doc goals, such as SEO non doc • Gather champions/product evangelists
  45. 45. Tips and Tricks • Post Videos on YouTube • Post Podcasts on iTunes • Post Presentations on • Post PDFs (etc.) on • Embed all on your website, blog, etc. (code provided)
  46. 46. Putting It All Together g g • Have solid (traditional) UA as a foundation ( ) • Supplement as is logical • If Web 2.0 initiatives embraced, monitor and nurture – You are the expert; don’t ignore it – Goals beyond doc – Use Google Alerts to follow your industry
  47. 47. IN CONCLUSION …
  48. 48. You are not alone ALL Information professions are p changing… • Journalism • Public Relations • Marketing
  49. 49. A final thought g This is EXTREME continuous publishing … Your “b k” will never b fi i h d! :-) Y “book” ill be finished! )
  51. 51. More Information Books Groundswell: Winning in a World Transformed by Social Technologies by Charlene Li and Josh Bernoff Wikipatterns b St Wiki tt by Stewart Mader tM d Website:; Blog: Wikinomics: How Mass Collaboration Changes g Everything by Don Tapscott and Anthony D. Williams The Paradox of Choice: Why More is Less by Barry Schwartz The Wisdom of Crowds by James Surowiecki
  52. 52. More Information Articles STC Intercom Web 2.0 issue Sept/Oct. 2007 The Wisdom of the Chaperones by Chris Wilson htt // Sl t lt /id/2184487 What is Web 2.0: Design Patterns and Business Models for the Next Generation of Software by Tim O’Reilly O Reilly 5/09/30/what-is-web-20.html What do you want from Social Media? social-media/
  53. 53. More Information 10 Best Intranets of 2008 (Jakob Nielsen) ( ) Web 2.0 Neglecting Good Design ( (Jakob Nielsen/BBC) ) 5 Uses for a Wiki at Work (Chris Brogan) uses for a wiki at http://www lifehack org/articles/technology/5-uses-for-a-wiki-at- work.html SharePoint: Wiki While You Work (Mauro Cardarelli) http://technet microsoft com/en us/magazine/cc162514 aspx Company Blogging 101 (Matt Cutts)
  54. 54. More Information The Content Wrangler Community g y Id I’d Rather Be Writing blog (includes TechWriter Voices podcasts)
  55. 55. Conferences Web 2.0 Summit WikiSym – International Symposium on Wikis Page SOBCon – Biz School for Bloggers http://www sobevent com/
  56. 56. Questions Contact information: Nicky Bl i l Ni k Bleiel ComponentOne Pittsburgh, PA nickyb@componentone com Blog “Technical Communication Camp Technical Camp” x Podcast on T h Writer Voices/Interview with Tom Johnson Pd t Tech W it V i /I t i ith T Jh Analyzing Your Users and Needs Before Creating help Deliverables