Done… and feeling pretty darn proud of that

January 16, 2010

A few posts back, I blogged about needing help with my Help project. Of the psychological variety. What a pounding headache that project gave me. Here are some of the lessons I’ve learned.

Outline, outline, outline!

The time you spend organizing a help system is arguably the most important part of the project and should not be performed at the end, as I did.  I’d already written the manuals in the doc set and turning my attention to the Help forced me to shift gears from a task-based focus to a software focus.  I had to remind myself repeatedly not to get lost in the GUI screens.  Users could do thirty or forty procedures from one screen. Holy crow, where do I start? Context Sensitive  Help means uses can arrive at a particular help topic ‘out of context’.  Since my job is to provide that context, the importance of being organized was a point not driven home with such significance until then. I wish I’d done this sort of software-against-task analysis before I’d started the other documents in the set because what resulted from this effort was a better, crisper, more focused information set.

I began with the very first screen users view upon launching the software and compiled a list of activities – NOT procedures  – they can do, as well as a list they may want to do.  That list became the outline. I had to create several Help-only topics, even though I use a single-source authoring tool.  If I hadn’t already written the manuals, I might have been able to do a more effective job at single-sourcing. So, from Screen One, users could perform three main activities. Those three main activities became chapters in the Help contents.  By grouping related procedures, I was able to distill a master list of just several over-arching activities and build from there.

Which brings me to my second lesson.

Link, link, link!

One rut I out of which I’m trying desperately to claw is writing for sequential reading. The internet makes page turning a thing of the past. Information Elements, chunking, single sourcing – all these methodologies emphasize the need to develop content that can stand on its own.  If you want to perform a task, here’s a task chunk. You want more information? Here’s a concept chunk.  As I assembled the Help system, I noticed I’d failed to connect all these related chunks in any manner other than sequential because I’d already written ‘books.’  I went through the entry point topics, linked them to corresponding concept, task, and related information topics, as well as to the table of contents.

When I published the project and it failed, I thought I was doomed. Two days later, after painstakingly reassembling the master file one topic at a time, testing it… lather, rinse, repeat… I finally found the problem. I’d directed my publishing tool to omit a topic from the master table of contents, but left its child topics still set for inclusion. That one little checkbox took two days to find and disable.

So, lesson three is test as you go and then, test again.

When I, at long last, had ensured every link worked, every topic published, and every entry point into the system was not a dead end, I happily delivered the system to my development team, so that they can link topics to the Help buttons.

Project management decided to postpone the effort until the next release.

Final lesson – mental health professionals must be on speed dial.



  1. Congratulations Patty! I loved reading this post. I could really feel your sense of panic, triumph, frustration and ultimately humour. Your finding that you had to create a number of topics for online help only jives with my experience too. Online help, and particularly context-sensitive help, is a different medium from the “book” type guides and so does need separate topics here and there. The wins are the topics that you can share.

    LOL, loved your final lesson. At least you can say that you’ve got guaranteed “delayed gratification”. 😉


  2. Thanks, Sarah! The project is nearly done and then I’ll switch gears back to my YouTube videos. I must admit, despite the headache and frustration and delayed gratification, I’ve never had this much fun at work.


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: