Issue 58, 2 April 2002
In this issue...
Using a gerund phrase for procedure topic titles
Are chapter numbers necessary?
More on gender-neutral writing
New technical editing discussion group
Editing using Microsoft Word 2002 (XP)
New "Business Tips" section of my website
New book - Taming Microsoft Word 2000 now available
Tracking advertising results: Adminder
Newsletter server: AWeber
I host this website on Server101
Diversify your business and your income
Late last year, TECHWR-L members (http://www.raycomm.com/techwhirl/) discussed whether the title or heading for procedural topics should be gerund phases (for example, "Creating a New Document" or "Changing the Modem Settings") or some other verb form, such as "Create a New Document" or "To create..."
One person asserted that gerunds can be difficult for a translator or a non-native English speaker to understand. Others responded that while a non-native speaker with limited fluency in English might stumble over gerunds, they should not be a problem for a translator (and if they are, you need to find a new translator).
Several people did agree that starting the title with some verb form was a good idea, because it helps ensure that you're organizing your topics by tasks.
If you're writing for non-native English speakers, you might consider using the imperative or infinitive form rather than the gerund (and you'll probably want to simplify other aspects of the writing too). Just be sure that you consistently use whatever form you choose.
An aside: I've found that many writers who use gerunds for procedural topic titles or headings then feel obligated to use gerunds for *all* headings, for the sake of consistency or parallelism -- and that some editors enforce this requirement. However, I think it's unnecessary to use a verb to start a heading for a non-procedural topic, just so all the headings are in the same form.
This problem of heading parallelism was mentioned in an article titled "Artificial tasks or real tasks?" in issue 51 of this newsletter. Gretchen Hargis et al., in "Developing Quality Technical Information: A Handbook for Writers and Editors", discussed pseudo-tasks, headings that start with vague verbs such as "understanding" and "learning" and (sometimes) "using."
Responding to a question on the TECHWR-L list, I said, "If it's going to be printed or distributed as PDF (a sequential file), I think chapter numbers are a good idea, because people are used to them and expect them."
When I wrote that, I couldn't remember seeing a book-like document that didn't have chapter numbers *and* that was well organized and "worked" for me. Upon further reflection, I recalled some environmental impact statements and other reports that didn't have chapter numbers and didn't suffer in the least from the lack, but I wasn't thinking of them as "books" even though many of them are book length.
A day later, I saw a "book" that worked well without chapter numbers and, in fact, might well have suffered if chapter numbers had been present. That book is the PDF User's Guide for The HyperText Studio from Olsonsoft, http://www.olsonsoft.com/. Each chapter after the Introduction is a clearly-labeled stand-alone tutorial for one major output or feature of the program, and each chapter contains sections labeled "Lesson 1. xxxx" "Lesson 2. xxx" etc. The chapters aren't sequential; in many ways the book is like a collection of short documents.
So, as with most things in technical writing, the answer to the question "Are chapter numbers necessary?" is probably "It depends."
Jan Henning email@example.com read my article on TECHWR-L http://www.raycomm.com/techwhirl/magazine/writing/genderneutral.html and wrote to me with some comments. Here is our correspondence.
Jan: ... I don't quite agree with two details
in the article:
- You advise to not use "his or her" at all, putting it on the same level as, e.g., "s/he". I occasionally use the construct, and while I agree that it is not the most elegant, it may still be preferable to alternatives in a given situation. The key is, though, to use it very sparingly.
Me: Well, I did say "avoid," not "don't use," but I agree it would have been better not to group "he or she" with "he/she" and "s/he," implying that all those phrases are equally objectionable. Certainly "he or she" (and "his or her") may be preferable to the alternatives in some circumstances and are quite acceptable when used sparingly.
Jan: - You advocate the sentence "The successful applicant's skills will contribute to the commission's work in remote areas." I do not feel that this is good language: Skills do not contribute to work, persons do. You have avoided writing "his or her" or something similar, but the cost is, in my opinion, too high.
Me: It's a pretty poor sentence no matter how it's written, because it says almost nothing. Now that you point it out to me, I see that the word "skills" isn't necessary at all; one could say just as much (or as little) with "The successful applicant will contribute...," a phrase that talks about the person. Thank you for that insight!
The STC's Technical Editing SIG has started a discussion group. To subscribe, go to the Web site at http://lists.stc.org/cgi-bin/lyris.pl?enter=stctesig-L
Click Join stctesig-L, enter your email address, choose settings for Status and See Your Messages, and select a password for yourself. A confirmation email will be sent to you.
Recent issues of Woody's Office Watch and Woody's Office for Mere Mortals have been discussing problems with Track Changes and other features of Word 2002 (XP) that editors often use. If you use, or are considering upgrading to, Office XP, and if you use features such as Track Changes or Word Count, you need to read these articles. Subscribe or download back issues of these free publications at http://www.woodyswatch.com/
I'm developing a new section of my website for employees and independent (self-employed) people who need to deal with business issues related to getting more work, increasing income, marketing services and products, working remotely, and using the internet in a variety of ways. That covers most of us, whether we like it or not! Start at http://www.jeanweber.com/business/index.htm
I've finally revised and updated my book "Taming Microsoft Word" with additions and changes specific to Word 2000. At the moment it's only available in downloadable PDF form; I should have printed copies available by the end of April. You can read the table of contents here: http://www.jeanweber.com/books/tameword.htm. That page also gives information on pricing and how to order. If you bought "Taming Microsoft Word" after January 1, 2002, you can upgrade to a PDF of the new edition at a reduced price.
I've recently started using Adminder, an ad-tracking service, and I recommend it to anyone who is doing any kind of marketing on the Web. For more information, visit this site.
AWeber is a paid service that provides follow-up autoresponders and other functions in addition to acting as a mailing list server. I use AWeber for sending out this newsletter, and I recommend them. Learn more here.
My new web hosting company offers me more than twice the space for less than half the cost of my old hosting company. I've been very happy with the service, so I recommend it to you. Learn more here.
While you've been reading the above, thousands of people all over the world have been working to put money in my pocket. By this time next week, YOU could be making extra money too. Get full no-obligation information here.
© Copyright 2002, 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.
This newsletter is no longer being published.
I do not sell, rent, or give my mailing list to anyone.