Looking for a development methodology for help systems

[CregganG]

I have been using Robohelp for a little over a year now to maintain a legacy help system that has a lot of problems with it.  I have an opportunity at the end of this year to develop the help system in Robohelp for a new software application and I would like to be able to start this project off on the right foot.  Can anyone recommend books or online resources with details on a development methodology that can be used to analyze a software application and produce a well-designed, organized, and useful help system?  It has been difficult for me to tell whether the books and online resources I have found so far will actually be helpful if I purchase them.

[RoboColum_n_]

Hi CregganG and welcome to the RH community.

The obvious one is DITA although this is not for everyone. If what you are really after is some sort of best practice for creating a help file from scratch, that is a very different question and will probably solicit different answers from different people. What I'd suggest is look at (and use) the help files for programs installed on your PC. After awhile you'll learn from what is good, bad and indifferent.

The key to a good help file is keeping your audience at the forefront of your mind. What is their level of experience? Where are they inside the application when they view a help topic? Where are they likely to go next? What do they need to complete a function? What is "nice to know" information? Is there too much or too little information in a topic? All of these (and other) questions are things you'll need to consider.

Think about presentation. Break up text by using bullets, tables, DHTML, etc. to break up text. Define your style guide before you start anything as this can help you when you come to document. Likewise think about whether you need a template or a new style sheet. Getting these sorted before you type anything will help you later.

As for content, create your TOC complete with empty topics first. This will help you get a feel for the help file structure and also help you ensure you have covered all the bases. Once you have this you can go back and fill in the topics. Don't worry of you have to delete/add topics. This is natural as you'll find it can evolve as you type.

These are just a few of the things I'd do. No doubt others will have other advice.

---

Read the RoboColum(n).

[MergeThis]

Reality check!

Get input from all stake-holders (management, development, marketing, etc.). They will probably have more influence on your help than anything else.

• Are there existing company style requirements? And are any changes in the works?
• Will your help be accessed on each user's machine, or over an intranet, or hosted on your company's web site?
• Will context-sensitive help be required? If so, will it be window-level or field-level as well?
• Will multiple writers be working this project? What are their skill levels in help authoring tools?

Without hard and fast answers to tat least these questions, you'll find the sands continuously shifting under your feet.

Good luck,

Leon

[CregganG]

Thanks!  DITA appears to be very useful.  DITA is more along the lines of what I was asking.  This article - http://tc.eserver.org/14378.html - is also related to my question, but not as practically useful as I was hoping it would be.

In my experience, users look for help in three different scenarios:

1. A user interface control is unfamiliar (e.g, a menu option, dialog box, or a button) and they want to know what it does.  I have seen help systems that handle this well.  This seems to be the typical organization for most help systems.
2. The user is a newbie and is just trying to get familiar with the software.  The organization of the TOC and the index can help with this.  Some of the help systems I have seen are really well-organized for this scenario, and other help systems -- not so much.
3. The user wants to know how to do some task in his or her job within the software.  I am having a hard time finding good examples in help systems for this scenario.  Admittedly, this is probably the hardest scenario for a technical writer.  In my experience, users just call a support helpdesk or send an e-mail to get an answer to "How do I do this task in this program?" since it can be really difficult to find in help systems.  It requires an in-depth understanding of the business processes that users have to complete on their job and then organizing help topics so they can be found based on business processes.

Software development has come a long way over the past few decades in applying methodologies to writing well-written, structured code that meets a user's needs.  I am curious if something similar exists for authoring help systems, especially in designing them so that all three of these scenarios are adequately addressed.

[Guest]

An approach for #1 and 3 together could be:

1. Create a set of help topics in the project to be linked from the application (context-sensitive help).
2. Create a set of topics in the project that are "how-tos," going through tasks and procedures.
3. In the CSH topics, provide links to related how-to topics.

Ben

GryphonMountain.net