Embed Size (px)
DESCRIPTION
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.
Citation preview
Enabling Science
Help! Fitting a square peg into a round hole
Technical Communications UK Conference21st – 23rd September 2010
Colum McAndrew (MISTC)Senior Technical Writer
Enabling ScienceSlide 2 © IDBS 2010
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)
Enabling ScienceSlide 3 © IDBS 2010
The E-WorkBook Suite
E-WorkBook
ChemBook BioBook
Enabling ScienceSlide 4 © IDBS 2009
The rough and the smooth
The good news was ...
There was no shortage of content.
Most of it was pretty accurate!
We had a mandate for change.
The bad news was ...
We had a disparate group of documents.
Some content lacked detail.
Little thought had been given to navigation.
Enabling ScienceSlide 5 © IDBS 2010
E-WorkBook Suite documentation
Training Reference Guides x 3
Assorted User Guides x 20 White Papers x 10
Help Files x 4
HTML Help(CHM)
ChemBook
BioBook
E-WorkBook
Enabling ScienceSlide 6 © IDBS 2009
The project objectives
Primary
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.
Secondary
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.
Enabling ScienceSlide 7 © IDBS 2009
The structure ...
Introductory documentation
General experiment documentation
Specific user base documentation
Enabling ScienceSlide 8 © IDBS 2009
Reminder of the project objectives
Primary
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.
Secondary
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.
Enabling ScienceSlide 9 © IDBS 2009
Context, detail and navigation
The key factors were:
The audience.
Providing only the detail users required.
Provide quick & easy access to additional information.
Enabling ScienceSlide 10 © IDBS 2009
Reminder of the project objectives
Primary
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.
Secondary
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.
Enabling ScienceSlide 11 © IDBS 2009
Implementing a consistent style
We realised that we:
Had all used various help files.
Knew what we liked / disliked.
Didn’t want to reinvent the wheel.
Enabling ScienceSlide 12 © IDBS 2009
Reminder of the project objectives
Primary
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.
Secondary
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.
Enabling ScienceSlide 13 © IDBS 2009
Documentation deliverables
Online documentation provided us the ability to update in “real time”.
Offline documentation provided a backup.
PDF requirement for one section of the help.
Enabling ScienceSlide 14 © IDBS 2009
Reminder of the project objectives
Primary
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.
Secondary
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.
Enabling ScienceSlide 15 © IDBS 2009
User interaction
Explain complex workflows.
Provide context to a specific audience.
Compliment (not replace) the written text.
Used Adobe Captivate simulations to:
Enabling ScienceSlide 16 © IDBS 2009
Reminder of the project objectives
Primary
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.
Secondary
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.
Enabling ScienceSlide 17 © IDBS 2009
Reusable content
Standardisation of style.
Ability to dynamically update content (e.g. version numbers, product names).
Let our HAT take the strain.
The key drivers for reusable content were:
Enabling ScienceSlide 18 © IDBS 2009
Reminder of the project objectives
Primary
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.
Secondary
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.
Enabling ScienceSlide 19 © IDBS 2009
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.”
Enabling ScienceSlide 20 © IDBS 2009
Questions?
Enabling ScienceSlide 21 © IDBS 2010
Contact Details
Contact Method
Contact Detail
www.cmcandrew.com/robocolumn
@robocolumn
Colum McAndrew
