Posted on

Madcap Flare: Logo Size and Settings for WebHelp


Want to replace the default MadCap Flare logo for your online help?

Before you do, a few things to consider:

  • For IE 6 or older uses — save the logo as GIF with a transparent background. If you use PNG, the transparent portion of your image appears as black.
  • For IE 7 or newer — save the logo as PNG with a transparent background.
  • HTML 5 skin — create the logo 60 pixels high. The width depends how far you want it to stretch across the header.

One suggestion is to create the logo 55 pixels and leave a 5 pixel border to set it off from the other UI elements.

  • HTML 5 DARK skin — use white (or another light color) for the text to contrast with the dark background.
  • HTML 5 LIGHT skin — use… go on, have guess what color? J

Save the image somewhere you’ll remember, for example to your Content/Images folder.

Posted on

Web Help: 5 Index Guidelines


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:

  1. Document Type — product documentation, user guide, operations manual, etc.
  2. Terminology — industry-specific, product-specific, and author-specific.
  3. Audience characteristics — background, education, current skills, familiarity with your product or competitive products.
  4. 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?

Posted on

Robohelp: Why Short Topic Names Improve Navigation

The length of the topic title, i.e. the number of characters, needs to be considered when creating topics for online help.

fuel-signLet’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.

This reduces:

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.

Let me know.

Posted on

Does your technical writing have an accent?

Maybe you don’t hear your accent, but others do. When you read their documents, does the accent come through? Continue reading Does your technical writing have an accent?

Posted on 4 Comments

Are technical documents a waste of time?

“Don’t worry” she said. “No one reads this stuff anyway. Just get it done.” Sounds familiar? Continue reading Are technical documents a waste of time?

Posted on

How to Write a Target Audience Questionnaire

Creating a training plan? Before you do this, you need to step a step back and work out what your colleagues need to learn. Continue reading How to Write a Target Audience Questionnaire

Posted on 4 Comments

Favorite 10 Technical Writing Tools

drinking sheepI’ve used the same technical writing tools for the last 5 years. A few products have come across my desk but nothing that really blown me away.

Here’s a run-down of what I use to write my technical documents. No order of preference. Which should I keep? Which should I replace?

Continue reading Favorite 10 Technical Writing Tools

Posted on 18 Comments

Robohelp vs Doc-to-Help? Which is best for Online Help?

Robohelp or Doc-to-Help?

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.

For Doc-to-Help

  • 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.

Against Doc-to-Help

  • 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.

For Robohelp

  • 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

Against Robohelp

  • Price
  • 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.

Another alternative is Madcap Flare.

What do you think?

If you were in my shoes, what would you do?

Posted on

Why use Master Templates in Adobe FrameMaker?

Master templates let you control the format and positioning of every component in your FrameMaker documents. They are very powerful when they work correctly, but be careful. If you make a mistake, it will take many an hour to clean the documents. Continue reading Why use Master Templates in Adobe FrameMaker?

Posted on 1 Comment

3 Tricks to Sharpen Your Screenshots

Diagrams, charts, and images all serve to enhance academic, business and technical documents. Without them the reader’s attention would flag and their interest wane. Continue reading 3 Tricks to Sharpen Your Screenshots

Posted on

How much can I make as a Tech Writer?

The median expected salary for a typical Technical Writing Supervisor 1 in the United States is $57,580.

The Salary Wizard at 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

Net Paycheck Estimate $ 1,644.97

Take a look at the charts over at:


Talk is cheap. Use Yahoo! Messenger to make PC-to-Phone calls. Great rates starting at 1¢/min.