Newsletter

Issue 26, 5 November 1999

ISSN 1442-8652

Editor: Jean Hollis Weber
jean@jeanweber.com
http://www.jeanweber.com

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:

• To use in negotiations with developers and others, to agree upon what you will do and how it fits in with what they are doing
   
• As a refererence when the situation changes and you are unable to meet what they see as your obligations, or when they say "that's not what we agreed on" or "that's not what I had in mind" or "why is it taking so long?"
   
• As a memory jogger for you, later in the project

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.

• Analyze the software product and its intended users.
   
• Determine any constraints, such as how the help will fit into the product's documentation set, how the programmers will link the help to the product, who will maintain the help, whether the help will be translated into other languages, and how much time and money is available for the project.
   
• Estimate the time required to plan, write, and edit the help.
   
• Negotiate with developers and others to determine realistic requirements for the help, and to specify the type and timing of technical reviews and testing (and who will do the testing).
   
• Choose professional technical communicators to write, index, and edit the help. Choose professional usability experts to advise, evaluate, and test the help as it is planned and developed.
   
• Choose a help authoring tool and any other required software and ensure the writer and editor know how to use it.

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:

• If an editor is brought in too late in the project, when the help is essentially complete, editing is usually limited to checking spelling, grammar, and layout consistency. More substantive issues are either not addressed or cannot be fixed even when identified, because no time is left in which to make the changes.
   
• This problem is worse when the help has been written by someone other than a professional technical communicator, or it has been written by a team of communicators, without overall planning and coordination.
   
• If lack of planning means that too much work must be completed in the available time, the most likely steps to be dropped or curtailed are editing, indexing and testing. Again, major problems may be found too late to fix.

(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 russgri@netbci.com 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 text...is 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.

http://www.jeanweber.com/links/tools.htm

Back to top

---

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

Mylene Pepin mylene.pepin@discreet.com 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.

---