The Technical Editors' Eyrie Newsletter

Issue 27, 19 November 1999

ISSN 1442-8652

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

In this issue...

News: I can now accept credit cards
News: I'm not attending the WinWriters conference after all
Feature article: The editor's role in an online help project (Part 2)
Defining editing and the top five rules
Additions to tools pages: Word and WordPerfect editing macros; FrameMaker tools and resources
Follow up: Planning online help
Follow up: Journal for layout/graphics/pre-press person
Subscription information

News: I can now accept credit cards

I can now accept credit cards in payment for my book. I'm using a service called Multicards, which handles more credit cards than I've ever heard of! There's a link from my book page http://www.jeanweber.com/books/e-edit.htm.

If you're interested in checking them out, they're at http://www.multicards.com/

I chose them because they could handle all my requirements:

I didn't have to be a resident of the USA
I could accept payment for services and for both tangible and intangible goods
Their fees were acceptable
I didn't have to use their shopping cart service
I could adapt the order page to fit my site's appearance

I looked at quite a few similar services, each of which failed on one or more of my criteria. If my expected turnover were higher, I could find other alternatives, with higher startup and monthly fees but lower per-transaction costs.

News: I'm not attending the WinWriters conference after all

In issue 25, I mention that I would be presenting a session titled "Usability testing for editors" at the WinWriters Online Help Conference in San Diego next March. http://www.winwriters.com/. Sadly, I've had to cancel that appearance due to probable conflicts with an appointment for cataract surgery.

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

In issue 26, I started 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.

Step 2. Develop high-level design specifications

Based on the analysis done in step 1, the documentation team now needs to develop high-level design specifications for the help. At least one technical communicator should be involved in the software design, which is likely to be taking place at the same time.

High-level help design specifications should include decisions on such issues as what information types, topic types, window types (primary, secondary, popup, tri-pane, etc), and navigation aids will be used; and whether to use audio or video files. See Chapter 2, Design specifications for online help for more information.

During this step, develop a high-level sample of the help, evaluate it, and revise as necessary. Ensure that the help design will fit in with what the programmers intend to do.

A writer or editor should also be involved with the design of the software interface. This person can look at such issues as: are the instructions, icons, field names, and other words and graphics appropriate for the audience? If the developers make changes in the design phase, instead of leaving the writers to explain confusing things at length in the help, everyone's job will be easier, and the result will be much better for the user.

Benefits of this step

With a plan for the online help, everyone on the project knows what's expected, and doesn't have to take time later in the project figuring out what to do. The help should then end up very consistent, so the users know where to expect help, what sort of help to expect, and where they can navigate from any type of help topic.
Help is easier for testers to test and for technical reviewers to review.
Errors in help implementation are easier to detect.
The online help development process is perceived by others on the project as much more rigorous and disciplined, and the technical writers' professional standing increases accordingly.

Editor's role in this step

The main role for an editor at this step is to ensure that help design specifications include all necessary decisions.
The editor might be responsible for compiling the specifications, or advising the responsible person.
Another role for the editor is to examine the software interface design and recommend changes.

Problems if this step is not done

Common problems if this step is skipped are:

The writer will have to pay more attention to those issues during the writing stage, and is more likely to forget something.
The help interface may be poorly done or inconsistent (particularly if more than one writer is involved).
Later in the project, the editor's work will be greater and will probably include many more consistency changes and negotiations over terminology and other issues. The chance of correcting problems later is low, due to time constraints.
Help is more difficult and time-consuming to review and test; problems may be overlooked if time is short.

Step 3. Develop detailed design specifications

Develop detailed design specifications for the online help. Include writing conventions, terminology, and style sheets and templates for topic types. Ensure that terms match those to be used in the user interface and the printed documentation, and that any consistency issues (between the help, the interface, and the printed documentation) are resolved. Consider translation and accessibility issues.

Even when only one writer is involved, a project leader needs to consider what happens if that writer leaves the project before it is complete, and who will maintain the help in future releases.

See Chapter 2, Design specifications for online help for more information.

Benefits of this step

With a plan for the detailed look-and-feel of the online help, everyone on the project knows what's expected, and doesn't have to take time later in the project figuring out what to do.

The help should then end up very consistent, so the editor is looking mainly for deviations from the plan.

New members of the team can quickly come up to speed and fit their writing into the overall look and feel of the help.

Editor's role in this step

An editor should be the person responsible for the detailed design. This is one of the two most important planning steps, in terms of the "helpfulness" of the help (the other is the task analysis).

The editor needs to develop a project-specific style guide or style sheet to record specific decisions about the format, presentation, and content of the help topics or other online documentation that will be provided for the project. The best mix of online help is different for different applications. Work with the writer and the project leader when making the decisions.

Problems if this step is not done

Lack of a detailed design, particularly on a project involving more than one writer, usually leads to inconsistency in all aspects of the help interface, including style, terminology, content, presentation, topic types, and navigation. Correcting these inconsistencies takes more time later in the project.

Step 4. Develop a detailed task list

The technical communication team now needs to develop a detailed task list from the intended audience's point of view. Task analysis may involve use cases, user scenarios, and other techniques.

In addition, try to think of the questions that users (novice, intermediate, and experienced) might ask. See Chapter 3, Strategies for editing and testing online help, and Chapter 7, Catering for novices to experts, for suggestions.

From the task and question lists, you can begin building a list of help topics. This list will probably evolve as the project progresses.

This is one of the two most important planning steps, in terms of the "helpfulness" of the help (the other is the detailed design specifications).

Benefits of this step

These lists form the basis of the writer's help topics and your editorial review of the index, the table of contents, and the overall "helpfulness" of the help. If these lists are compiled at this stage, the editor can check the writer's work more easily, and most issues (of what should be included) have been resolved.

Editor's role in this step

An editor should be involved in the developing the task and question lists, at least in reviewing and commenting on the lists.

Problems if this step is not done

Without task and question lists, the writer may forget to include some information that the users need, and the editor may fail to notice the omissions.

(To be continued next issue.)

Defining editing and the top five rules

In response to a question from someone about what it is to be an editor, Geoff Hart ghart@videotron.ca wrote:

"I coined the phrase 'professional idiot' some time back. The explanation is that as a substantive editor, the 'idiot' part of my job is to trip over _anything_ any reader, including me, could potentially trip over (even if they could eventually figure it out); in effect, that means you need to adopt a certain naivete towards the writing so that even if you're an expert in the subject, you can empathize with readers who aren't. The 'professional' part of the phrase means that I have to do more than trip; I have to figure out _why_ I tripped, and how to _fix_ the problem. (It also refers to the fact that I'm good at this, and get paid to do it, rather than doing it solely for the love of the job.)"

Another question was what are 'your top five cardinal rules of editing.' Here's Geoff's response:

First, do no harm: this means no harm to the author's intended meaning, reputation, or legal liability; no harm to the reader, such as by omitting necessary safety information; and no ethical harm, such as by knowingly distorting the truth.
Second, the reader's needs are paramount: if the author plans to publish, the goal is presumably to communicate with people who _don't_ live inside the author's head, and this means that the communication is inevitably centered on the reader's needs, not those of the author.
Third, the second rule notwithstanding, the author's needs are also important: recognition of the reader's needs never means that you get to eliminate the author's voice and conceal the author's joy in writing.
Fourth, recognize that some things are more important than others and that the time constraints in real-world editing mean that you often need to do triage: some things (e.g., comprehension) are crucial, other things (e.g., misleading typos, unclear antecedents) are less important but still need to be done, and other things (e.g., minor typos and minor inconsistencies) simply aren't important enough to worry about while there are still bigger fish to fry.
Fifth, understand that editing is collaborative, not dictatorial. Your job is to _help_ bring the author and reader together, not eliminate either from the equation. If you can keep this in mind while you edit, everything else tends to fall into place fairly naturally.

Additions to tools pages: Word and WordPerfect editing macros; FrameMaker tools and resources

I've added two more pages to the website:

Editing macros for Word and WordPerfect
Provided by Matthew Stevens mls@zeta.org.au
FrameMaker tools and resources
Too many to mention here, and more being added

Follow up: Planning online help

Michele Marques mmarques@cms400.com writes,

"Your article on editing online help is timely. I agree with you on the need for planning when supervising someone who has not written WinHelp before... this summer I supervised/edited a "complete novice" at creating WinHelp documentation. This fall when I edited the two files for publication/release, I found that the first file, where I was really specific in the planning, resulted in a document that was easy to edit, while the other - where I did not supervise as much, led to a document that required substantial re-writing."

Follow up: Journal for layout/graphics/pre-press person

Michele Marques mmarques@cms400.com writes,

"About journals for graphics/layout people, I do have a couple of suggestions. I get these magazines for free, but I don't know if they will send free to professionals in Australia.

Graphics Exchange - this journal comes out of Toronto and is great for good overall coverage. Lots of reviews and some great "how-to"/tips articles. For example, the current issue had an article on "Photoshop Techniques: Image Blending". The ultimate blend was a photo of a dog and cat in a human-style embrace on a sofa, but there were lots of other blending examples and instructions for effects and other common uses.
Contact information:
   Brill Communications Inc.
   25 Elm Avenue
   Toronto, Ontario
   Canada M4W 1M9
   Tel: 1-416-961-1325
   Fax: 1-416-961-0941
   gxo@tube.com
new media.pro - Another journal out of Toronto, this one is useful for graphics and multi-media professionals in on-line and broadcast production. It's only of occasional interest to someone exclusively involved in print production. (June 2003 note: website not found.)

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.

Articles © Copyright by their authors.
© Copyright Jean Hollis Weber, Technical Editing Consultant
WeberWoman's Wrevenge, Airlie Beach, Qld., Australia, jean@jeanweber.com
ABN 18 005 740 467

Last updated 1 June 2003