Cool Tools for Technical Writers

9,992 views

Published on

Once you’ve convinced an employer that you know how to write, can play well with others, and are curious about technology, you need to demonstrate your mastery of the authoring tools they require on the job. But which authoring tools should you master? Jeff Haas, past president of STC Atlanta, discusses the tools that are currently in demand and the ones that are likely to be in demand in the very near future.

Cool Tools for Technical Writers

  1. 1. Cool Tools forTechnical WritersPDF available at www.stcatlanta.org
  2. 2. Who Is Jeff Haas? • Lead Technical Writer at ADP • Associate Fellow at STC • Past President of STC Atlanta • haas@pobox.com
  3. 3. Agenda • Introduction • 1st Generation Tools • 2nd Generation Tools • 3rd Generation Tools • Q&A No demos
  4. 4. What Is a Cool Tool?A cool tool is an authoring tool thatenables technical writers to createsuperior user assistance thatimproves the user experience.
  5. 5. What Is an Authoring Tool? • Does not require programming • Contains programming features • Built on an authoring language • Allows you to import content from other formats • Allows you to generate content in multiple formats
  6. 6. A Cool Tool from the20th Century
  7. 7. Who Is a Technical Writer? Better Better User Users Interfaces
  8. 8. Facing the Facts • 8-14% of tech writing jobs were eliminated in the past two years • Salaries declined Personal email from Kathryn Burton, Chief Executive Officer of STC
  9. 9. STC Membership From a spreadsheet provided by Lloyd Tucker, Deputy Executive Director of STC
  10. 10. Employment Options • Become more like a User Interface Designer by authoring embedded procedural user assistance • Become more like an Instructional Designer by authoring external tutorial user assistance
  11. 11. The Status Quo Is Notan Option  User Interface Designer  Instructional Designer  Both  Status Quo
  12. 12. What Is User Assistance? • Provides guidance to someone using a software application • Includes all forms of help available to a user • Not limited to a traditional help system • Can include procedural and tutorial information
  13. 13. Tutorial versus Procedural
  14. 14. Tutorial User Assistance
  15. 15. Course Authoring Tools • Adobe Captivate • Articulate Presenter • Techsmith Camtasia
  16. 16. Procedural User Assistance
  17. 17. What Tools Do You Need? • 17 Application Pages • Embedded Text Topics – 49 • Page-Level Help Topics – 12 • Field-Level Help Topics – 18 • System Messages – 155
  18. 18. Start at the End
  19. 19. Tech Writing Timeline
  20. 20. 1st Generation Platform:Mainframe Computers
  21. 21. 2nd Generation Platform:Personal Computers
  22. 22. 1981 ─ IBM PC
  23. 23. 1990 ─ Windows 3.0
  24. 24. 1990 ─ Windows Help
  25. 25. 1991 ─ RoboHelp
  26. 26. Context-Sensitive Help
  27. 27. 2nd Generation Cool Tools• Adobe RoboHelp or Madcap Flare• Adobe FrameMaker and/or MS Word• Graphics Tools – Techsmith Snagit – Microsoft Visio – Adobe Photoshop• Adobe Acrobat
  28. 28. Help Authoring Tools:Overview Either/or: • Adobe RoboHelp • Madcap Flare Honorable Mention: Author-it
  29. 29. Help Authoring Tools:Adobe RoboHelp For More Information
  30. 30. Help Authoring Tools:Adobe RoboHelp • Content for help systems, policies and procedures, and professional knowledgebases • Multichannel, multidevice publishing • Collaborative reviews, reusable assets, and dynamic user-centric content • User-generated content and moderated or stored commenting
  31. 31. Help Authoring Tools:Adobe RoboHelp
  32. 32. Authoring Tools:RoboHelp
  33. 33. Help Authoring Tools:RoboHelp Jeff’s take: • Industry standard • Everyone has a horror story but still uses it • Helped my career
  34. 34. Help Authoring Tools:Madcap Flare For More Information
  35. 35. Help Authoring Tools:Madcap Flare • Content authoring tool • Print and online documentation • Complex digital print publishing (PDF) or online Help systems (WebHelp and WebHelp Mobile)
  36. 36. Help Authoring Tools:Madcap Flare
  37. 37. Help Authoring Tools:Madcap Flare Jeff’s take: • Good alternative from former RoboHelp developers • Customizable, but requires some post-processing • Use as XML Editor?
  38. 38. Help Authoring Tools:Comparison Based on information provided in MadCap Flare Certified Test Review + Developers Guide by Scott Deloach (available at www.amazon.com)
  39. 39. Word Processors:Overview Both/and: • Microsoft Word • Adobe FrameMaker
  40. 40. Word Processors:Microsoft Word For More Information
  41. 41. Word Processors:Microsoft Word • Standalone or bundled with Office or Works • First released in 1983 as Multi- Tool Word for Xenix systems • Started on IBM PCs running DOS (1983) and Windows (1989)
  42. 42. Word Processors:Microsoft Word
  43. 43. Word Processors:Microsoft Word Jeff’s take: • Default word processor • Business letter producer that got out of control • Nightmarish for robust technical doc (sections, TOC, Index, master documents, callouts)
  44. 44. Word Processors:Adobe FrameMaker For More Information
  45. 45. Word Processors:Adobe FrameMaker • Authoring and publishing solution for unstructured, structured, and XML/DITA/S1000D content • Document processor for the production and manipulation of large structured documents
  46. 46. Word Processors:Adobe FrameMaker
  47. 47. Word Processors:Adobe FrameMaker Jeff’s take: • Still best option for robust doc • Desktop publishing tool (PDF) • Book metaphor • Use as XML Editor?
  48. 48. Graphics Tools:Overview • Screenshot Utilities • Diagramming Software • Image Editing Software
  49. 49. Screenshot Utilities:Overview • Techsmith Snagit • Inbit FullShot
  50. 50. Screenshot Utilities:Techsmith Snagit For More Information
  51. 51. Screenshot Utilities:Techsmith Snagit • Windows only • Replaces the native Print Screen function with additional features • Contains most features needed by technical writers
  52. 52. Screenshot Utilities:Techsmith Snagit
  53. 53. Screenshot Utilities:Techsmith Snagit Jeff’s take: • Industry standard, good tool • New features include capturing embedded objects like links, pictures, and multimedia • Upload to Flickr, etc.
  54. 54. Diagramming Software:Overview • Microsoft Visio • CorelDRAW
  55. 55. Diagramming Software:Microsoft Visio For More Information
  56. 56. Diagramming Software:Microsoft Visio • Commercial diagramming program for Windows • Uses vector graphics to create diagrams
  57. 57. Diagramming Software:Microsoft Visio
  58. 58. Diagramming Software:Microsoft Visio Jeff’s take: • A fun tool to use • Great for creative brainstorming • Used for processes, software architecture, and organization charts
  59. 59. Image Editing Software:Overview • Adobe Photoshop • Corel PaintShop Photo Pro (Cheaper) • GIMP (Free)
  60. 60. Image Editing Software:Adobe Photoshop For More Information
  61. 61. Image Editing Software:Adobe Photoshop • Graphics editing program • 2003 "Creative Suite" rebranding led to Photoshop 8 renamed as Photoshop CS • 12th major release of Photoshop
  62. 62. Image Editing Software:Adobe Photoshop
  63. 63. Image Editing Software:Adobe Photoshop Jeff’s take: • New version is nothing short of astonishing • Content-aware feature • Disappearing man and Sydney opera house
  64. 64. Conversion Utilities:Overview • Adobe Acrobat Pro Extended • Webworks ePublisher • Calibre
  65. 65. Conversion Utilities:Acrobat Pro Extended For More Information
  66. 66. Conversion Utilities:Acrobat Pro Extended • Family of application software • View, create, manipulate, print and manage files in Portable Document Format (PDF) • Commercial software except Adobe Reader (formerly Acrobat Reader)
  67. 67. Conversion Utilities:Pro versus Reader • SharePoint integration • Office 2011-ready • PDF Portfolios • Panels interface • Improved OCR • Enterprise deployment • Acrobat X suite
  68. 68. Conversion Utilities:Pro versus Reader • Protected mode security • Sticky notes and highlighter • Improved browser integration • Simplified panels interface • Enterprise deployment • Reader for Android
  69. 69. Conversion Utilities:Adobe Acrobat Jeff’s take: • How could we live without it? • Adobe continues to make significant upgrades • Move from printing Postscript files to saving PDFs using PDFMaker?
  70. 70. Abraham Maslow Quote“If the only tool you have is a hammer, youtend to see every problem as a nail.”
  71. 71. 3rd Generation Platform:Mobile Cloud Computers
  72. 72. Cloud Architectures From Windows Azure Platform: Cloud Development Jump Start"
  73. 73. User Assistance Requirements
  74. 74. Darwin Information TypingArchitecture (DITA)From The State of Structured Authoring by Pringleand O’Keefe (available at www.amazon.com)
  75. 75. Authoring Tools for DITA From The State of Structured Authoring by Pringle and O’Keefe (available at www.amazon.com)
  76. 76. Content ManagementSystem for DITAFrom The State of Structured Authoring by Pringleand O’Keefe (available at www.amazon.com)
  77. 77. 3rd Generation Cool Tools:Procedural User Assistance• XML Editor• Content Management System – Document-Centered – Low-End Component – Propriety Component – Open Component• Translation Management System
  78. 78. XML Editors:Overview • JustSystems XMetaL Author • SyncRO Soft <oXygen/> XML Editor
  79. 79. XML Editors:XMetaL Author For More Information
  80. 80. XML Editors:XMetaL Author • Create and edit documents in XML and SGML • Similar features to word processors but native XML editor • Configure to work with standard and custom DTDs and XML Schema
  81. 81. XML Editors:XMetaL Author
  82. 82. XML Editors:XMetaL Author Jeff’s take: • Good for DITA • Easy to update • Automates workflow • Easy to integrate with CCMS like Trisoft DITA?
  83. 83. XML Editors:<oXygen/> XML Editor For More Information
  84. 84. XML Editors:<oXygen/> XML Editor • Multi-platform XML editor, XSLT/XQuery debugger and profiler with Unicode support • Java application that can run in Windows, Mac OS X, and Linux
  85. 85. XML Editors:<oXygen/> XML Editor
  86. 86. XML Editors:<oXygen/> XML Editor Jeff’s take: • Cheaper than XMetaL • UI not quite as intuitive • Doesn’t integrate as easily with CMS? • Good alternative
  87. 87. Content Management:Overview • Document-Centered: SharePoint • Crowdsourcing Wiki: Confluence • Low-End Component: Subversion • Proprietary Component: Author-it • Open Component: SDL Trisoft DITA
  88. 88. Content Management:Microsoft SharePoint For More Information
  89. 89. Content Management:Microsoft SharePoint
  90. 90. Content Management:Microsoft SharePoint Jeff’s take: • Document-centric • Only used internally • Does not support components such as DITA objects
  91. 91. Content Management:Atlassian Confluence For More Information
  92. 92. Content Management:Apache Subversion For More Information
  93. 93. Content Management:Apache Subversion Jeff’s take: • Poor man’s CCMS • Supports components such as DITA objects • Version control and content management
  94. 94. Content Management:Author-it For More Information
  95. 95. Content Management:Author-it Jeff’s take: • True integration (XML Editor/CCMS/Translation) • Proprietary • Must “marry” the company • Doesn’t support true DITA output
  96. 96. Content Management:SDL Trisoft DITA For More Information
  97. 97. Content Management:SDL Trisoft DITA Jeff’s take: • True DITA integration with XML editors like XMetaL • Open source, non-proprietary • Haven’t seen it in use yet
  98. 98. Translation Management:SDL WorldServer For More Information
  99. 99. Q&A“The key to success is helping others bydoing what you love.”─Me

×