Resources for writing Online Help

http://en.wikiversity.org/wiki/Technical_writing

Is the online help already written or are you starting from scratch?  Your approach will vary based on complexity of the software, the audience, if it needs to single-source to a printed manual, localize into other languages. etc.

The two most common online help tools I know of are:

RoboHelp -- http://www.adobe.com/products/robohelp.html

MadCap Flare -- http://www.madcapsoftware.com/products/flare/overview.aspx

I used to be a tech writer and would be glad to answer some of your questions.  I personally wouldn't get too hung up on tech writing books... I would spend more time looking at lots of online help examples and find some you like and copy them.  Seriously.  Most tech writing books are very theoretical, and they drive me bonkers trying to decipher them.

Lots of online help now is much more blog-like and video-based.  More traditional help includes written procedures, FAQs, field definitions, etc.   Is it going to be reference doc or more like a tutorial where they learn how to use the software?  These are just a few things to ask yourself.

The Online Help is already written using Robohelp (English-only, yes, it becomes a big fat PDF help doc too), but I find it to be rather user-unfriendly.  It feels much too segmented; to understand one screen, you usually have to follow a bunch of links to get the full picture.  I want to change this approach, but I wasn't sure if it makes sense to do so.  Maybe the older version follows specific online help guidelines that were well-researched and proven?  I guess I thought the Online Help world might have its own version of the ADDIE model (if you catch my drift)?  But I haven't been able to find anything like that.

I did find an article on the 7 golden rules of online Help design (yay!  rules!), and rule #1 was "Don't force users to move between topics to solve a problem...[Users] are best served by including within a single topic all the information they need to answer their question or solve their problem, even if it means duplicating information that appears in other topics".  This is exactly the opposite of the old writer's approach, but totally in line with how I'd like to write (and re-write) it.

So I'm really searching for rules/guidelines/ justifications to know that I am writing an online help that will best serve our customers.  (We have some video-based stuff too, but we wouldn't be able to transform the entire Help into video-stuff).

Thank you for your response!  Do my ramblings trigger any other suggestions you could offer?

The extra info helps!  Here are a couple things that come to mind...

1.  Check out STC for resources -- it's like ASTD for tech writers -- http://www.stc.org/

2.  If it's a big complex help system -- sounds like it is -- just try to learn her standards and design and maintain it the way it is for a release or two so you have plenty of time to focus on learning the tool first.  It gives you time to research before tackling big changes.

3.  Most indexes are terrible and extremely hard to maintain.  If you can, just rely on the full-text search, which is what most users use.

4.  You have to look at the help from every direction -- 1) online reference (coming to find one thing), 2) tutorial (trying to learn how to complete a process of multiple procedures), 3) printed user guide.  That's the biggest challenge in OLH design -- making it work well for all three.  If the software has context-sensitive help tied to help topics, you need to learn that structure quickly from the developers so you don't break it accidentally.

5.  Before changing anything, I'd survey the customers if possible to find out what's working, not working, so you don't change something they rely on and love.

6.  Decide on one module you can change first and test drive it for several months with beta testers before converting everything.

Your training background will help -- it's just communicating complex information in an easy-to-understand way (when done properly).  Trust your instincts on the design changes, but realize there are a million ways to do everything... go with the way that works best for the users of the software.

Just my rambling thoughts at the end of the day.  Hope something in here helps!

By the way, my old documentation group had an internal reference manual that defined each topic type we had in the help system.  Let's see how many I can remember -- Procedure, Process, Field Definition, Window, FAQ, Concept... there might have been a couple more, but that's about it.  We had standard ways to approach each topic type.  That helped with consistency.  If she has a bunch of topic types like this, then I'd write a document writing out something like...

For every Procedure topic...

Title (font type / size / required or optional)

overview text (font - normal)

Prerequisites (font - Subhead)

links to other procedures

To do xyz (font - Subhead)

1. step one (font - Number)

It's a standards doc for each topic type for your reference.  It helps a ton.

Heather,

Thank you so much for taking the time to respond.  This is exactly the sort of guidance I was searching for.  (And thanks for the STC link.  I hadn't found that group yet, and will definitely explore all that they offer).  You are definitely right about #2...stick with her style/standards for a bit.  I only have 4 weeks left before Baby Hull is due and will be taking maternity leave.  Then I can tackle the rest.  Nonetheless, I don't feel quite so overwhelmed now, and you've really set me in the right direction.

Thank you, thank you!