Alternatives to the Paragraph

'It's all in the manual.' How many times have you heard that - or said it in frustration? After all, when you are the person who wrote the manual, you know that all the answers are there. But time and again readers can't find what they need to know, or don't understand the material. Before you blame the reader, look again at how you've presented the material.

Hollis Weber, Jean. Technical Editors Eyrie (1989). Articles>Editing>Technical Writing

Audience and Document Analysis

Before you begin editing a document, try to find out as much as you can about the audience for the document and purpose of the document.

Hollis Weber, Jean. Technical Editors Eyrie (2001). Articles>Writing>Audience Analysis>Rhetoric

Choosing and Using a Technical Writer

Offers advice for anyone looking to hire a technical writer on choosing a writer and using a writer.

Weber, Jean Hollis. Business Consulting News (1997). Careers>Advice>Management

Choosing and Using Help Topics

This paper describes some common types of help topic and when to use each. Different applications require different mixes of help topics. Choose the topic types that are appropriate for the application you are documenting.

Hollis Weber, Jean. Technical Editors Eyrie (1999). Articles>Documentation>Online>Help

Deciding What Needs to be Done

Before you begin editing a document, you need to analyse it and plan what needs to be done. The exception is when your job is strictly limited (by your supervisor or the client) to correcting only the glaring errors of spelling, punctuation and grammar (a 'light edit'). There is no point to attempting a more substantive edit if doing so will only get you into trouble (or if the client won't pay you for the time you spend).

Hollis Weber, Jean. Technical Editors Eyrie (2001). Articles>Editing>Project Management

Developing a Departmental Style Guide

As a technical writer, you may be asked to develop a style guide for the hardcopy and online documents you produce. Sounds easy enough. After all, commercial style guides and, potentially, examples shared by your colleagues should provide enough information to get you started. In researching your task, though, you may find a variety of definitions and explanations of what a style guide is and why companies use them. What's more, you many find that style guides don't seem to have consistencies among them that can help guide you in developing one.

Weber, Jean Hollis. TECHWR-L (1998). Articles>Style Guides>Workflow

Editing for Gender Neutrality

How to be politically correct without mangling the English language. The goal is that the reader should not notice the writing.

Weber, Jean Hollis. Technical Editors Eyrie (1998). Articles>Writing>Style Guides>Gender

Editing Online Materials

Editing anything that is intended to be read on a computer rather than (or in addition to) being read on a paper copy.

Weber, Jean Hollis. ASTC (1996). Articles>Editing>Online

Editing Reports and Proposals

Businesses, non-profit organizations, government departments, and other groups produce a lot of proposals and reports. This article summarizes some features of reports and proposals that are not the same as books, news items, manuals, magazine articles, memos and many other documents.

Hollis Weber, Jean. Technical Editors Eyrie (2001). Articles>Editing>Proposals>Reports

Editing Single-Sourced Projects

This article does not address the (important) questions of when a single-sourcing methodology is a good solution to an information delivery problem ('good' here meaning saving time and money while maintaining or improving the quality of the resulting deliverables). Instead, I'm looking only at the editor's involvement in the project.

Hollis Weber, Jean. Technical Editors Eyrie (2002). Articles>Editing>Single Sourcing

Editing Tables of Data

Tables should allow readers to easily and accurately: see what subject matter and variables are being described; find out absolute values; observe relationships between variables. When you edit a table, it is useful to assess just how well it achieves these ends. Readers will feel confident with your table if they can quickly navigate around and absorb the data.

Hollis Weber, Jean. Technical Editors Eyrie (1999). Articles>Editing>Technical Editing

Electronically Indicating Approvals or Rejections of Editorial Changes

This technique (involving two macros) works in Word97, but not in Word6 or 7/95. The requirement is to indicate (for audit purposes) whether an editorial change was accepted or rejected by the author or other authority.

Hollis Weber, Jean. Technical Editors Eyrie (2002). Articles>Editing>Software>Microsoft Word

Escape From the Grammar Trap

Too many editors focus on the details and don't pay enough attention to the bigger picture. Editors can--and should--add even more value through substantive, technical, and usability editing. Copyediting is important, but the details are only part of what an editor can and should be reviewing. After all, a document can be correctly spelled and punctuated, grammatically correct, use only approved terminology, and follow the style guide perfectly--and still not serve the audience's needs. This article covers some reasons why editors focus on details and not the bigger picture; describes how much attention technical communicators should pay to formal rules of grammar, punctuation, and usage; and describes how we can distinguish between essential and nonessential rules of grammar, punctuation, and usage.

Weber, Jean Hollis. TECHWR-L (2002). Articles>Editing>Grammar

Ethics in Scientific and Technical Communication

Discusses many ethical issues including: taking personal responsibility for one's actions, Behaviour toward colleagues, subordinates and others,Dealing with experimental subjects, interviewees, etc, Telling the 'truth', and choosing between advocacy and objectivity.

Weber, Jean Hollis. WISENET Journal (1998). Careers>Advice>Ethics

An Example of Substantive Editing

Some years ago I edited a quarterly magazine for the users of a large Australian computing network. This example (from 1985) is fairly typical of the technical articles I received from department managers. I include here the unedited text and my revised version.

Hollis Weber, Jean. Technical Editors Eyrie (2001). Articles>Editing>Case Studies

Example Style Guide  

This document accompanies the TECHWR-L article 'Developing a Style Guide,' and includes a sample outline of a style guide. Some of the sections include some detailed sample text; others do not. Please note that the examples shown here are not necessarily the 'correct' choices, or the 'preferred' choices, or the 'best' choices; they are simply examples of things to include. Your project may require additional items, especially if your writing will be used on a Web site.

Weber, Jean Hollis. TECHWR-L (1998). Reference>Style Guides

Gender-Neutral Technical Writing

In recurring discussions on the TECHWR-L list, many technical writers argue that they write in 'correct English' and are not going to change their style just to suit the political-correctness police. 'I won't use 'they' as a singular pronoun because it's not grammatically correct' and 'Using contrived phrases such as 's/he' is just too awkward' are arguments I've heard frequently in the debate. But using 'incorrect English' or contrived phrases is neither the goal nor the outcome of gender-neutral writing.

Hollis Weber, Jean. Technical Editors Eyrie (2002). Articles>Writing>Technical Writing>Gender

Gender-Neutral Technical Writing

Gender-neutral writing uses language that does not stereotype either sex nor appear to be referring to only one sex when that is not the writer's intention. In this article, you'll see why gender-neutral writing is important for technical writers to use, what gender-neutral writing is not, and how you can use gender-neutral writing in the documents you develop.

Weber, Jean Hollis. STC Northeast Ohio (2002). Articles>Writing>Technical Writing>Gender

Gender-Neutral Technical Writing

Gender-neutral writing uses language that does not stereotype either sex nor appear to be referring to only one sex when that is not the writer's intention. In this article, you'll see why gender-neutral writing is important for technical writers to use, what gender-neutral writing is not, and how you can use gender-neutral writing in the documents you develop.

Weber, Jean Hollis. TECHWR-L (2002). Articles>Writing>Style Guides>Gender

Grammar, Punctuation, Spelling

The Web abounds with sites teaching grammar, punctuation, and spelling. Not surprisingly, most of these sites are provided by educational institutions, teachers, or business-writing consultants, presumably to make up for the lack of grammar teaching in so many school systems for the past several decades. Some are tutorials (masquerading as style guides) for technical communicators. Here are a few sites that I have found useful or that other people have recommended to me.

Weber, Jean Hollis. Technical Editors Eyrie (2002). Articles>Style Guides>Writing

Hints for Developing a Table of Contents

Planning a project before beginning the detailed work is one of the vital steps to success in technical communication. Developing a table of contents is one of the steps in the planning process of a document.

Hollis Weber, Jean. Technical Editors Eyrie (2002). Articles>Editing

OpenOffice.org and Me: An Introduction

When I first tried OOo, it was at around version 1.0.0 or 1.0.1. The help files were pathetic in those days; I described them at the time as 'badly written, badly organized, badly indexed, and frequently wrong.' To be fair, the help has improved a great deal since then, though the indexing still needs a lot of improvement.

Weber, Jean Hollis. O'Reilly and Associates (2004). Articles>Word Processing>Software>OpenOffice