Help! Fitting a square peg into a round hole: Technical Communication UK Conference 2010
Download as PPTX, PDF1 like396 views
The document outlines a technical communication project aimed at redesigning documentation for an e-workbook suite, focusing on structure, content accuracy, and user navigation. It details the project's objectives, deliverables, and the implementation of various formats, including online resources and tutorials, to accommodate different learning styles. User feedback indicates a positive reception, highlighting improved navigation and varied content formats.
Help! Fitting a square peg into a round hole: Technical Communication UK Conference 2010
- 1. Colum McAndrew (MISTC)Senior Technical WriterHelp! Fitting a square peg into a round holeTechnical Communications UK Conference21st – 23rd September 2010
- 2. Pause for thought..."Documentation is like sex. When it's good, it's very, very good and when it's bad, it's better than nothing.“Karen Mulholland (@kemulholland)
- 4. The rough and the smoothThe good news was ...There was no shortage of content.
- 5. Most of it was pretty accurate!
- 6. We had a mandate for change.The bad news was ...We had a disparate group of documents.
- 7. Some content lacked detail.
- 8. Little thought had been given to navigation.E-WorkBook Suite documentationE-WorkBookHelp Files x 4Training Reference Guides x 3BioBookHTML Help(CHM)ChemBookAssorted User Guides x 20White Papers x 10
- 9. The project objectivesPrimaryRedesign the structure of the documentation.
- 10. Rewrite the content with due reverence to context and navigation.
- 11. Provide sufficient detail to the desired audience.
- 12. Implement a consistent style.SecondaryHost the documentation online (RoboHelp Server).
- 13. Provide CHM files as backup.
- 14. Provide users with movie tutorials for additional context.
- 15. Reuse content as much as possible.The structure ...Introductory documentationGeneral experiment documentationSpecific user base documentation
- 16. Reminder of the project objectivesPrimaryRedesign the structure of the documentation.
- 17. Rewrite the content with due reverence to context and navigation.
- 18. Provide sufficient detail to the desired audience.
- 19. Implement a consistent style.SecondaryHost the documentation online (RoboHelp Server).
- 20. Provide CHM files as backup.
- 21. Provide users with movie tutorials for additional context.
- 22. Reuse content as much as possible.Context, detail and navigationThe key factors were:The audience.Providing only the detail users required.Provide quick & easy access to additional information.
- 23. Reminder of the project objectivesPrimaryRedesign the structure of the documentation.
- 24. Rewrite the content with due reverence to context and navigation.
- 25. Provide sufficient detail to the desired audience.
- 26. Implement a consistent style.SecondaryHost the documentation online (RoboHelp Server).
- 27. Provide CHM files as backup.
- 28. Provide users with movie tutorials for additional context.
- 29. Reuse content as much as possible.Implementing a consistent styleWe realised that we:Had all used various help files.Knew what we liked / disliked.Didn’t want to reinvent the wheel.
- 30. Reminder of the project objectivesPrimaryRedesign the structure of the documentation.
- 31. Rewrite the content with due reverence to context and navigation.
- 32. Provide sufficient detail to the desired audience.
- 33. Implement a consistent style.SecondaryHost the documentation online (RoboHelp Server).
- 34. Provide CHM files as backup.
- 35. Provide users with movie tutorials for additional context.
- 36. Reuse content as much as possible.Documentation deliverablesOnline documentation provided us the ability to update in “real time”.Offline documentation provided a backup.PDF requirement for one section of the help.
- 37. Reminder of the project objectivesPrimaryRedesign the structure of the documentation.
- 38. Rewrite the content with due reverence to context and navigation.
- 39. Provide sufficient detail to the desired audience.
- 40. Implement a consistent style.SecondaryHost the documentation online (RoboHelp Server).
- 41. Provide CHM files as backup.
- 42. Provide users with movie tutorials for additional context.
- 43. Reuse content as much as possible.User interactionUsed Adobe Captivate simulations to:Explain complex workflows.Provide context to a specific audience.Compliment (not replace) the written text.
- 44. Reminder of the project objectivesPrimaryRedesign the structure of the documentation.
- 45. Rewrite the content with due reverence to context and navigation.
- 46. Provide sufficient detail to the desired audience.
- 47. Implement a consistent style.SecondaryHost the documentation online (RoboHelp Server).
- 48. Provide CHM files as backup.
- 49. Provide users with movie tutorials for additional context.
- 50. Reuse content as much as possible.Reusable contentThe key drivers for reusable content were:Standardisation of style.Ability to dynamically update content (e.g. version numbers, product names).Let our HAT take the strain.
- 51. Reminder of the project objectivesPrimaryRedesign the structure of the documentation.
- 52. Rewrite the content with due reverence to context and navigation.
- 53. Provide sufficient detail to the desired audience.
- 54. Implement a consistent style.SecondaryHost the documentation online (RoboHelp Server).
- 55. Provide CHM files as backup.
- 56. Provide users with movie tutorials for additional context.
- 57. Reuse content as much as possible.User feedback was, well, impressive.“Looks really good and is easy to navigate. Good balance of new user and advanced user sections.”“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.”“Wow! Very Impressed. Nice piece of work by the team.”“Every time I play with the new help I am more impressed. I take my hat off to you.”
- 58. Questions?
- 59. Contact Details
Editor's Notes
- #2: 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.
- #10: Open a browser at the E-WorkBook 9.0 help file.Open the System Administration > 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
- #14: 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.
- #16: 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 ...
- #18: 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.”