Do you provide an index for your online documents?
I’m not sure if today’s customers actually want an index. Maybe they prefer to search.
Of course, not everyone agrees with me.
Lori Lathrop, author of An Indexer’s Guide to the Internet, helps firms index their technical publications for software, manufacturing, and science.
She highlights four points when indexing documentation:
Document Type — product documentation, user guide, operations manual, etc.
Terminology — industry-specific, product-specific, and author-specific.
Audience characteristics — background, education, current skills, familiarity with your product or competitive products.
Audience objectives — needed skills, tasks to be performed.
A nice set of guidelines to get us started.
But what about if you’re moving your documents online.
Do you still need to index the content?
Does a good Search function replace the need for an index?
Indexing Online Help
The team at Adobe RoboHelp provides the following guidelines when creating an index for online help:
#1 Prioritize user needs first
Focuses on their tasks and way of thinking.
Consider their backgrounds and knowledge.
Use words and phrases they’re likely to think of when looking for information.
Users can and do form impressions about the usefulness and value of a Help file based on their experience with the index – and in this case, perception is reality.
If they can’t locate information in the index, users may doubt whether or not the information exists in the Help file. If users are consistently taken to the wrong topics or to unexpected topics, they may doubt the accuracy of the Help file.
#2 Index the most important words
Include only those words and phrases your users are most likely to look up.
You don’t have to index every word or phrase – like “About” or “Working with.”
For ideas on good index entries, look at the features and content of your Help system – topic titles, headings, tables, examples, and so on.
Include terms commonly used by both beginners and experts.
#3 Provide multiple ways to access the same information
As user may not be familiar with the terms and concepts used in your Help system, provide synonyms and alternate index entries.
Include verbs, noun phrases, and synonyms to reach the widest range of users.
Index your competitors’ terms, too – users may not know the name of the feature in your Help system, but they might know what it’s called in your competitors system.
#4 Use consistent access routes
Use consistent phrasing throughout the index.
Include inverted terms and headings – what the command is as well as what the command does.
This approach helps users find information regardless of whether they’re looking for the command or the action the command accomplishes. (For example, Printing:Landscape, Landscape:Printing.)
#5 Provide enough detail for users to choose
Provide enough description with your index entries so users can determine which path to choose.
Users should be able to tell the difference between index entries that lead them to conceptual overviews and entries that lead them to tasks.
I’m still in two minds about creating an index. What do you think?
Is providing an index a thing of the past?
Do users prefer a search engine to an index instead?
The length of the topic title, i.e. the number of characters, needs to be considered when creating topics for online help.
Let’s say you’re creating different topics in RoboHelp. Procedures, reference, and conceptual materials. Each of these needs an intuitive and meaningful name. That makes sense.
However, you also need to consider the length of the topic title (i.e. the number of characters) when it appears in the side Navigation.
The side Navigation appears on the left of the Help system when viewed online.
Topic Title: Name Length
The problem with the length of the topic title is that, depending on the user’s settings, they may only see the first two or three words.
So, if I wrote:
the length of the topic title
they’d only see
the length of [and the rest would be hidden behind the frame]
which isn’t much use.
One way to fix this is to frontload – put the most important word or phrase first – and then add the rest. For example:
[6 words] Topic Title: Length of the Name or
[5 words] Topic Title: Length of Name or
[4 words] Topic Title: Name Length
Remember, users scan for information. If you frontload the critical word, term, phrase, or verb, the user is likely to find the relevant information faster. It also means they don’t have to drag the navigation pane to see the rest of the topic title.
This may not seem important – can’t they just drag it? – but with more of us reading content online, using different devices, different browsers, and on small screens, making the user have to work harder to find information is best avoided.
Remove clutter from headings
A second tactic is to delete filler text or phrases that add little value.
In the example above, we reduced the word count from six to five to four. Was anything lost in the process? Not much.
You can also delete filler phrases, such as Descriptions in Reference Descriptions of the XXX Window, as description is implied. In other words, the user knows they’ll be getting descriptions of the window, for example. Likewise, words such as Information can also be deleted.
A final suggestion is to remove definite articles.
Reference Descriptions of the XXX Window
Reference for XXX Window
These are different ways to reduce the length of the topic title and the number of characters when creating online help.
With that said, what’s more important is not to reduce or change the headings to make them shorter but understand why we need to do this. How can we improve the help system for the user?
Maybe there’s a smarter way to create topic headings.
My client has given me permission to use whatever tool I want to do the next batch of tech docs — and they’ll buy the software. No cost to me.
Which one should I choose?
Robohelp or Doc-to-Help
Doc-to-Help was the first help authoring tool (HAT) I used in my technical writing career. We’re talking quite a while back now. Since then Robohelp has overtaken it as the tool of choice for technical writers, especially as it’s now owned by Adobe and bundled with its Technical Communications software pack.
I feel this product is under-estimated. Other technical writers (more knowledgeable than me about HATs) recommend it.
Opportunity to broaden my skillsets (self-interest here and not to the client’s advantage!)
Rapid response from Component 1 (product owners) when I contacted them. Very helpful. Only Techsmith (esp Betsy Weber) were more helpful.
Price is not cheap
Will there be enough qualified Doc-to-Help experts to take over this project when I move on?
Does it integrate with other technical writing apps and/or Microsoft Word?
Worried about lack of community support, i.e. from other technical writers, if I need help.
Oceans of Doc-to-Help experts to take over this project
Part of the Adobe Tech Communication suite. Maybe get discount.
Arguably the industry standard
Plenty of tutorials online if I get stuck
Concern that there is no real advantage in getting the Tech Communication suite anyway as we (i.e. the client) won’t use it once I’ve left
Found the user interface horrible to work with last time. Admittedly, this was four years ago but you know how these things stick.
The Salary Wizard at salary.com has some terrific interactive tools for finding the base salaries, average salaries, and top paying roles in this field.
They also offer the “Basic Salary Report based on broad national data, reported exclusively by HR depts of thousands of employers from all sizes, industries and locations.”
Although these numbers are based on national data, the results are most similar to the data from companies with approximately 1,000 employees. If your company is bigger, smaller or in a unique industry, we strongly recommend using a premium report to ensure the most accurate answer.”
Based on their calculations, your Estimated Paycheck Results would be:
Bi-weekly Gross Pay $ 2,214.62 Federal Withholding $ 400.23 Social Security $ 137.31 Medicare $ 32.11 State $ 0.00