Colum McAndrew (MISTC)<br />Senior Technical Writer<br />Help! Fitting a square peg into a round hole<br />Technical Commu...
Pause for thought...<br />"Documentation is like sex. When it's good, it's very, very good and when it's bad, it's better ...
The E-WorkBook Suite<br />E-WorkBook<br />ChemBook<br />BioBook<br />
The rough and the smooth<br />The good news was ...<br /><ul><li>There was no shortage of content.
Most of it was pretty accurate!
We had a mandate for change.</li></ul>The bad news was ...<br /><ul><li>We had a disparate group of documents.
Some content lacked detail.
Little thought had been given to navigation.</li></li></ul><li>E-WorkBook Suite documentation<br />E-WorkBook<br />Help Fi...
The project objectives<br />Primary<br /><ul><li>Redesign the structure of the documentation.
Rewrite the content with due reverence to context and navigation.
Provide sufficient detail to the desired audience.
Implement a consistent style.</li></ul>Secondary<br /><ul><li>Host the documentation online (RoboHelp Server).
Provide CHM files as backup.
Provide users with movie tutorials for additional context.
Reuse content as much as possible.</li></li></ul><li>The structure ...<br />Introductory documentation<br />General experi...
Reminder of the project objectives<br />Primary<br /><ul><li>Redesign the structure of the documentation.
Rewrite the content with due reverence to context and navigation.
Provide sufficient detail to the desired audience.
Implement a consistent style.</li></ul>Secondary<br /><ul><li>Host the documentation online (RoboHelp Server).
Provide CHM files as backup.
Provide users with movie tutorials for additional context.
Upcoming SlideShare
Loading in …5
×

Help! Fitting a square peg into a round hole: Technical Communication UK Conference 2010

688 views

Published on

This was an Adobe sponsored use case study into how IDBS implemented Adobe's Technical Communication Suite to deliver a major rewrite of the help for their flagship product.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
688
On SlideShare
0
From Embeds
0
Number of Embeds
174
Actions
Shares
0
Downloads
11
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide
  • Make sure you open the following windows:The PowerPoint demo.A browser window open at the EWB 9.0 help file.The System Administration RoboHelp project.Notepad file.
  • Open a browser at the E-WorkBook 9.0 help file.Open the System Administration &gt; Entities and Flexible Hierarchy book.EXAMPLE ONEDisplay the Entities Overview topic.Summarise and point out the:Overview that forms part of each book.Summary at the start of most topics.Overview process and links to steps.Open the Maintaining Entity Types topic from the TOC.Summarise and point out the:Overview that forms part of each topic.Note box.Click on the Default Entity TypesTell Me About drop down.Summarise and point out the:Table contains a lot of vital information.Would otherwise have required a separate topic and additional navigation.Click on the Create an Entity TypeHow Do I drop down.Summarise and point out the:Procedural steps.Tip box.Further dialog fields dropdown. The idea being that if you know the fields to complete you don’t need to see them.Table with mandatory fields first.EXAMPLE TWOOpen the Adding Entities to the Navigator topic.Point out the following:SummaryProcedure for Adding Entities to the Navigator.“Tell me about” and “See also” sections.Expand the first “Tell me about” link.Point out the following:SummaryDialog – point out the icons on the right (cut, paste, delete).Drop downs
  • Open the RoboHelp application which should have theSystem Administration project open.Open the Adding Entities to the Navigator topic.Point out the hashed areas in the:HeaderSee also bullets.Recreate the topic using …Preview the topic.Add a build tag expression of Not CHM and Not Dummy.Click on the Creating an Experiment link.Add a build tag expression of Not Dummy and Not WebHelp.Click on the Creating an Experiment link.
  • Open a browser with the E-WorkBook 9.0 help file displayed.Open the Movies book.Click on the Spreadsheet Table Layout Movies topic.Click on the Moving Dimensions to Change the Layout link.Show the movie.Create a demo movie ...
  • Open the RoboHelp application which should have theSystem Administration project open.Open the Adding Entities to the Navigator topic.Point out the greyed out area for “See also”, “Tell me more” and “How do I”.Display the Variable pod.Create a variable called TCUK with a value of 2010.Display the Snippets pod.Create a snippet called Last night with a value of “What was I thinking of. You would have thought that I’d have learnt years ago that drinking and dancing until the early hours leads to a feeling of malice the following day.”
  • Help! Fitting a square peg into a round hole: Technical Communication UK Conference 2010

    1. 1. Colum McAndrew (MISTC)<br />Senior Technical Writer<br />Help! Fitting a square peg into a round hole<br />Technical Communications UK Conference<br />21st – 23rd September 2010<br />
    2. 2. Pause for thought...<br />"Documentation is like sex. When it's good, it's very, very good and when it's bad, it's better than nothing.“<br />Karen Mulholland (@kemulholland)<br />
    3. 3. The E-WorkBook Suite<br />E-WorkBook<br />ChemBook<br />BioBook<br />
    4. 4. The rough and the smooth<br />The good news was ...<br /><ul><li>There was no shortage of content.
    5. 5. Most of it was pretty accurate!
    6. 6. We had a mandate for change.</li></ul>The bad news was ...<br /><ul><li>We had a disparate group of documents.
    7. 7. Some content lacked detail.
    8. 8. Little thought had been given to navigation.</li></li></ul><li>E-WorkBook Suite documentation<br />E-WorkBook<br />Help Files x 4<br />Training Reference Guides x 3<br />BioBook<br />HTML Help(CHM)<br />ChemBook<br />Assorted User Guides x 20<br />White Papers x 10<br />
    9. 9. The project objectives<br />Primary<br /><ul><li>Redesign the structure of the documentation.
    10. 10. Rewrite the content with due reverence to context and navigation.
    11. 11. Provide sufficient detail to the desired audience.
    12. 12. Implement a consistent style.</li></ul>Secondary<br /><ul><li>Host the documentation online (RoboHelp Server).
    13. 13. Provide CHM files as backup.
    14. 14. Provide users with movie tutorials for additional context.
    15. 15. Reuse content as much as possible.</li></li></ul><li>The structure ...<br />Introductory documentation<br />General experiment documentation<br />Specific user base documentation<br />
    16. 16. Reminder of the project objectives<br />Primary<br /><ul><li>Redesign the structure of the documentation.
    17. 17. Rewrite the content with due reverence to context and navigation.
    18. 18. Provide sufficient detail to the desired audience.
    19. 19. Implement a consistent style.</li></ul>Secondary<br /><ul><li>Host the documentation online (RoboHelp Server).
    20. 20. Provide CHM files as backup.
    21. 21. Provide users with movie tutorials for additional context.
    22. 22. Reuse content as much as possible.</li></li></ul><li>Context, detail and navigation<br />The key factors were:<br />The audience.<br />Providing only the detail users required.<br />Provide quick & easy access to additional information.<br />
    23. 23. Reminder of the project objectives<br />Primary<br /><ul><li>Redesign the structure of the documentation.
    24. 24. Rewrite the content with due reverence to context and navigation.
    25. 25. Provide sufficient detail to the desired audience.
    26. 26. Implement a consistent style.</li></ul>Secondary<br /><ul><li>Host the documentation online (RoboHelp Server).
    27. 27. Provide CHM files as backup.
    28. 28. Provide users with movie tutorials for additional context.
    29. 29. Reuse content as much as possible.</li></li></ul><li>Implementing a consistent style<br />We realised that we:<br />Had all used various help files.<br />Knew what we liked / disliked.<br />Didn’t want to reinvent the wheel.<br />
    30. 30. Reminder of the project objectives<br />Primary<br /><ul><li>Redesign the structure of the documentation.
    31. 31. Rewrite the content with due reverence to context and navigation.
    32. 32. Provide sufficient detail to the desired audience.
    33. 33. Implement a consistent style.</li></ul>Secondary<br /><ul><li>Host the documentation online (RoboHelp Server).
    34. 34. Provide CHM files as backup.
    35. 35. Provide users with movie tutorials for additional context.
    36. 36. Reuse content as much as possible.</li></li></ul><li>Documentation deliverables<br />Online documentation provided us the ability to update in “real time”.<br />Offline documentation provided a backup.<br />PDF requirement for one section of the help.<br />
    37. 37. Reminder of the project objectives<br />Primary<br /><ul><li>Redesign the structure of the documentation.
    38. 38. Rewrite the content with due reverence to context and navigation.
    39. 39. Provide sufficient detail to the desired audience.
    40. 40. Implement a consistent style.</li></ul>Secondary<br /><ul><li>Host the documentation online (RoboHelp Server).
    41. 41. Provide CHM files as backup.
    42. 42. Provide users with movie tutorials for additional context.
    43. 43. Reuse content as much as possible.</li></li></ul><li>User interaction<br />Used Adobe Captivate simulations to:<br />Explain complex workflows.<br />Provide context to a specific audience.<br />Compliment (not replace) the written text.<br />
    44. 44. Reminder of the project objectives<br />Primary<br /><ul><li>Redesign the structure of the documentation.
    45. 45. Rewrite the content with due reverence to context and navigation.
    46. 46. Provide sufficient detail to the desired audience.
    47. 47. Implement a consistent style.</li></ul>Secondary<br /><ul><li>Host the documentation online (RoboHelp Server).
    48. 48. Provide CHM files as backup.
    49. 49. Provide users with movie tutorials for additional context.
    50. 50. Reuse content as much as possible.</li></li></ul><li>Reusable content<br />The key drivers for reusable content were:<br />Standardisation of style.<br />Ability to dynamically update content (e.g. version numbers, product names).<br />Let our HAT take the strain.<br />
    51. 51. Reminder of the project objectives<br />Primary<br /><ul><li>Redesign the structure of the documentation.
    52. 52. Rewrite the content with due reverence to context and navigation.
    53. 53. Provide sufficient detail to the desired audience.
    54. 54. Implement a consistent style.</li></ul>Secondary<br /><ul><li>Host the documentation online (RoboHelp Server).
    55. 55. Provide CHM files as backup.
    56. 56. Provide users with movie tutorials for additional context.
    57. 57. Reuse content as much as possible.</li></li></ul><li>User feedback was, well, impressive.<br />“Looks really good and is easy to navigate. Good balance of new user and advanced user sections.”<br />“Love the variety of different formats (e.g. movie clips, sample files, worked examples). People have diverse learning styles so this is a good approach.”<br />“Wow! Very Impressed. Nice piece of work by the team.”<br />“Every time I play with the new help I am more impressed. I take my hat off to you.”<br />
    58. 58. Questions?<br />
    59. 59. Contact Details<br />

    ×