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.
Help! Fitting a square peg into a round hole: Technical Communication UK Conference 2010
1. Colum McAndrew (MISTC) Senior Technical Writer Help! Fitting a square peg into a round hole Technical Communications UK Conference 21st – 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)
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 > 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.”