Technical Editors' Eyrie Photo of Osprey
Resources for technical editors Home page About technical editing Books Tips, techniques and checklists Links to other resources Newsletter archives Site index Search this site Business basics: marketing, website development, and more



Issue 26, 5 November 1999

ISSN 1442-8652

Editor: Jean Hollis Weber

In this issue...

Feature article: The editor's role in an online help project
Tip: Choosing a tool to do a publishing job
Resource: Tools for online editors
Question time: Journal for layout/graphics/pre-press person
Subscription information

Feature article: The editor's role in an online help project (Part 1)

Over the next few issues, I'll be publishing excerpts from an early draft of the first chapter in a book I'm writing (working title: Editing Online Help). I'd be delighted to have feedback from readers, expanding on my draft, arguing with it, or asking questions that I might be able to answer in the next draft.

The importance of planning

The online help is as much a part of the user interface as any of the windows, dialogs, or web pages, and cannot be properly produced without due planning and design phases.

The help needs to fit into the overall documentation set for the software product, so it should be planned and coordinated with the other user documents, not in isolation.

Someone (for example, the documentation team leader, the lead writer, or the editor) should write a help design specification as part of the project plan (which also covers time and resource estimates).

Even if you are a lone writer, responsible for everything, you need a plan (that documents what you think needs to be done and how long it will take), for several reasons:

Steps in the ideal help project

The ideal help project would have unlimited time and resources to produce help that meets all the needs of its target audience. It would also be well planned and the development would proceed according to the plan.

As we all know, time and resources are always limited, so we have to make compromises. However, one of the compromises we should never make is to skip the planning stage of the project; yet this happens all too frequently.

Sometimes planning isn't done because the people involved don't realize how much they can do without knowing anything about the user interface for the software product. In fact, you can do most of the planning steps without this information, as long as you know what the product is supposed to do, and who the intended audience is.

Let's look at the steps involved in the ideal help project, why each step is important, the editor's role in each step, and what happens if the step is skipped.

Note: Steps 1 through 5 can be done before the software interface design is done, or in parallel with the software design.

  1. Analyze and plan the help project.
  2. Develop high-level design specifications for the help.
  3. Develop detailed design specifications for the help.
  4. Develop a detailed task analysis.
  5. Build and evaluate a prototype help system.
  6. Develop an outline and map of the help project.
  7. Write, index, and edit the help topics.
  8. Review the help topics, index and table of contents.
  9. Test the help stand-alone and with the product.
  10. Release the help with the product.
  11. Evaluate the help and plan for improvements.

Step 1. Analyze and plan the project

Planning might be done by the documentation team leader, the writer, the editor, or by all of these people contributing their particular expertise. Decisions arising from planning should be written down in a documentation plan.

The analysis and planning step has several sub-steps, several of which should be done at the same time.

Benefits of this step

Good planning vastly improves your chances of completing a project on time and within budget, while producing usable, helpful, correct, and complete help. Lack of planning almost ensures that the project will run into problems.

Editor's role in this step

The main role for an editor at this step is to ensure that professional technical communicators are involved early in the project, that time and resource estimates are realistic, that other constraints are identified and taken into account, and that the consequences of unrealistic decisions are made known.

Problems if this step is not done

Common problems for an editor if this step (or any part of it) is skipped are:

(To be continued next issue.)

Back to top

Tip: Choosing a tool to do a publishing job

On the TECHWR-L list recently, Russell Griechen wrote, "I need to do some technical writing for one of my projects. I have Microsoft Publisher. Since there is a lot of layout and strict placement of there a better [tool]?"

I responded,
The short answer is yes, there are better layout programs. The real question, however, is what's the best choice for your particular project? You haven't told us enough to know whether Publisher is suitable or not.

Two answers I've seen so far appeared to contain some unspoken assumptions about you and your project. If you are doing a class project or rarely need to produce this sort of document (you didn't say what sort it is or if it's a one-off or an ongoing requirement), then spending the relatively large sum of money to buy FrameMaker, and putting in the relatively large amount of time to learn to use it, is not necessarily the most appropriate choice.

There's no need to buy a Lear Jet when a small car will get you where you want to go -- especially if you have to learn to fly the Lear Jet before you can go anywhere.

If you already have Publisher 98 or 2000 and know how to use it, you might as well continue to use it unless you discover that it won't do what you want. It will in fact do quite complicated layout and is often used for newsletters and similar layout-intensive projects.

While I agree there are better tools, and I certainly wouldn't recommend (or even consider) Publisher for a documentation department, I think it could be quite adequate for many jobs involving strict layout. As, indeed, is Word.

On the other hand, if you know (or expect) that you'll be doing a lot of technical publishing, or if whatever you're writing is likely to need to be reused for other purposes, spending the time and money to get and learn a robust package like FrameMaker is definitely the better choice -- unless your clients insist on getting files from you in Word or some other package.

Back to top

Resource: Tools for online editors

I've started a new section on the website for tools for online editors and writers. It will provide links to several vendors of software tools that online editors and writers may find useful. It's a bit rudimentary at the moment, but there's more to come.

I don't intend to list the big, well-known tools like Word, FrameMaker, and Adobe Acrobat, but rather focus on less-known tools and add-ons. Please feel welcome to suggest your favorites.

Back to top

Question time: Journal for layout/graphics/pre-press person

Mylene Pepin writes, "I am the technical editor of of documentation group consisting mostly of around 12 writers and 1 layout/graphics/pre-press person. The latter reports to me. I've been looking for some kind of journal or newsletter that she could subscribe to and haven't found anything. STC doesn't seem to be geared for her needs. She needs a journal that would inform her of the best ways to do her job, the newest software. For myself, I've discovered the Editorial Eye, which I will subsribe to. I would appreciate any information you might have. We work for a software company that develops special effects."

I replied that although I knew of an Australian magazine, and I knew that there were several (probably quite a few) in the USA, I didn't know their titles or publishers. Can any readers help Mylene?

Back to top

© Copyright 1999, Jean Hollis Weber. All rights reserved.

You may forward this newsletter (in whole or in part) to friends and colleagues, as long as you retain this copyright and subscription information, and do not charge any fee.

Subscription information

This newsletter is no longer being published.

Privacy statement

I do not sell, rent, or give my mailing list to anyone.