Review: Top 10 Mistakes to Avoid when Starting a Help Project!

Help and Documentation thought leader has written an excellent White Paper on “Th e top 10 mistakes to avoid when starting an online help project” available for download as PDF. Adobe had Neil as an eSeminar guest earlier this year, and you can view the recorded Webinar, “Confessions of an ‘Enlightened’ Mind – Top 10 Mistakes to Avoid when Starting a Help Project!”. This blog gives s “Reader’s Digest” version of points made in both the white paper and eSeminar. We encourage you to read the paper and view the webinar to get a full sense of the challenges and solutions presented.

Neil has many years as a consultant helping craft Help solutions in a variety of formats, and he is also an expert in RoboHelp. I think you will find his advice highly useful.

According to Neil, two developments in recent years have magnified the possibility of making mistakes when planning a Help system:

Mistake #1: Misunderstanding the present

An old but common mistake is to misunderstand the difference between Web Help and WebHelp. They sound alike, but the first is a generic term for help on the web; the second is a specific browser-based output pioneered in RoboHelp in 1998 and now offered in one form or other by all help authoring tools.

The solution: Make sure you understand your online help output options and how they fit into your users’ configurations.

Mistake #2: Not preparing technically for the future

Help authors got away with practices like not following coding standards or exploiting authoring tool peculiarities. Such practices were once done proudly, a sign that the author was a rule-breaking renegade. Today, they’re increasingly seen as the cause of annoying and expensive-to-fix problems.

A good example of this is authors who common text formatting toolbar for local formatting instead of styles and CSS (cascading style sheets). Using styles is more efficient, consistent, faster, and makes automated format conversion possible. Improved tools, like RoboHelp’s Styles and Formatting pod make it easier to use styles for everything—text enhancements, like boldfacing, as well as traditional heading styles.

The solution: understand up-to-date practices and make maximum use of your authoring tool’s features.

Mistake #3: Not preparing managerially for the future

Very often, the documentation for a project that has to be updated or maintained is unavailable. The result is lost time during the update while the new authors reconstruct the project settings.

The solution: Document the project and update the documentation any time the project changes either technically or structurally.

Mistake #4: Not coordinating the help authoring with other groups

Help authoring used to be self-contained aside from asking Engineering about questions or context sensitivity integration with the application or review comments. But once help became HTML-based in 1997, more and more groups and standards began affecting help projects in ways that may be important but not always obvious. Help authors have to interact with these groups and follow these standards. If not, some technical decisions may not get made, or may get made in ways that are detrimental to the interests of the help projects.

The solution: Determine who is affected by and who and what affects the help projects and factor it into the projects. Help authors have to be prepared to take the initiative because some of the other groups may not think of taking it to the doc group.

Mistake #5: Not defining (and documenting) the development process

Help authoring has many steps and it’s easy to forget a few during development or when it’s time to publish the final version. The result being time wasted in having to go back to correct problems, embarrassment when users find a problem that was overlooked, or unnecessarily complicated development.

The solution: Develop and use project task checklists. It sounds silly, especially for experienced authors who know their projects. But it’s risky to trust memory. Experienced airline pilots use checklists, so should help authors.

Mistake #6: Not developing mechanisms to support content consistency

One of the hardest tasks in help authoring is developing structurally and terminologically consistent content. Without that consistency, the help is hard to use because readers have to take time away from understanding what the topics are saying to understanding how they’re saying it. Different terms make the content hard to search. A user who refers to a task as A and searches for it in a help system written by an author who calls that task B won’t find any hits and will conclude that the help is useless.

The solution: This can be made up of two parts. First, develop and use topic templates to get structural consistency between different topics of the same type—procedure, concept, reference, etc. Developing templates is tedious but fast and templates can be used in and amortized over multiple projects.

Second, see if the tool has features that help create consistent content, such as variables. For example, a variable called ‘sandwich name’ with a value of ‘hoagie’ can consistently insert the word ‘hoagie’ for us. We don’t type the name but simply tell the tool to insert the name of the variable – ‘hoagie’, until we change the variable value, at which point the name changes everywhere or an auto-complete feature that reads the first few letters of a word as we type it and offers to automatically complete it.

Mistake #7: Not developing mechanisms to support format consistency

Similar to the need for content consistency is the need for format consistency. I raised the issue of styles earlier as a management issue but it’s also a development issue, and important enough to revisit for emphasis. ‘Format consistency’ refers to content display—font, size, colors, etc. but it goes beyond text to issues like graphic position and size control, and table formatting. This consistency is not only important for authoring and reading, but also to follow online authoring trends towards removing all formatting from documents and putting it in the CSS instead.

The solution: Develop a CSS and as many table style sheets as needed, teach authors how to use them, make their use mandatory, and prohibit local formatting. Keep it simple; the harder the styles are to use, the less they will be used.

Mistake #8: Not revisiting a project’s design in light of ‘environmental’ changes

If this is your first help project, you’ve got a clean slate. But if this is not your first project, past experience can actually be detrimental. There is a tendency to repeat what was done in the past projects even if it may no longer be appropriate due to changes in the authoring and delivery environment (the term ‘environment’ refers to the technical environment in which the help must operate – the platform – Windows, Mac, UNIX, etc., the browser(s) – IE, Firefox, Chrome, etc., and location –local, network-drive, or server).

The solution: Check periodically with Engineering or IT about what may be changing in your distribution or configuration environment. Some environmental changes won’t affect help authoring, but some may. You need to find out before starting the authoring.

Mistake #9: Not planning to test QA and usability

Very often, we create help projects with no idea whether readers can use them. There are actually two sides to this—QA, whether a particular feature works at all and its usability, whether readers can find and understand how to use that feature in the first place. QA is tedious but necessary; the more broken links in a project, the more trouble users have with it and the more credibility it loses. I recommend setting up a series of rules for the types of errors to accept in a project.

The solution: I recommend to clients that, if nothing else, they create a few simple cases that ask test subjects to answer a question by using the help, then watch them try to find the answer to see if they can, how long it takes, and how painful the process was. Repeat this with a dozen people. You may not get statistically valid data but you can get a lot of good, often painful, feedback.

Mistake #10: Not planning to create an index

Authors often create online help with no index, assuming most readers will navigate using the search feature. In many cases, this is because we don’t like indexing or think there isn’t enough time to create an index. This has always been true in help authoring but has been aggravated in recent years by the spread of Google. Why create an index when users will just search?

The solution: Simply create an index. At a minimum, make each topic’s title an index entry. Better still, make each title and its inverse index entries. For example, for a topic called Print Dialog Box, create the index entries ‘Print Dialog Box’ and ‘Dialog Box, Print’.