Technical Editors Eyrie

Issue 54, 2 January 2002

ISSN 1442-8652

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

In this issue...

An example of substantive editing
Does a comma go inside or outside a closing quotation mark?
Emphasizing the most important issues in your style guide
What style guide to use?
Results of poll on plain text or HTML newsletters
Advertisements
   Copies of "Website Indexing" now available from me
   I host this website on Server101
   The website your boss doesn't want you to know about
   Books by Jean Hollis Weber
Subscription information

An example of substantive editing

Some years ago I edited a quarterly magazine for the users of a large Australian computing network. I've recently found a fairly typical example of the technical articles I received from department managers. These articles generally needed extensive editing, often essentially rewriting.

Because the example is a bit long, I haven't included it in this newsletter. Instead, the unedited text and my revised version are on this page: http://www.jeanweber.com/howto/makeover.htm

Does a comma go inside or outside a closing quotation mark?

Someone on the Technical Writers' List described a document convention that enclosed in quotes any literal text to be entered into a software control, and asked, if it becomes necessary (as part of the sentence describing the step to be taken) to include a comma after the quote-enclosed text, should the comma be placed inside or outside the quote marks?

Geoff Hart ghart@videotron.ca answered,
"I'd prefer to avoid the issue entirely, since truly literal readers will also type the quotation marks, no matter how carefully you explain that they shouldn't do this... My suggestion would be to format the instructions in the form of a two-column table. The left column contains the instructions, and the right column contains what (if anything) the reader must type... In this approach, you don't have to apply any formatting to the literal text to be typed. You must, however, make sure that the column titles for the table repeat on each new page, and that you rewrite the text slightly to make sure that the literal text comes at the end of a sentence, not in the middle. For example 'Type XXX and press return' would become two steps, the first being 'Type the text at right: XXX' and the second being 'Press return: [nothing]'..."

The questioner contined, "Grammar indicates it should go inside the quotes, clarity indicates it should go outside the quotes."

Geoff responded, "Actually, grammar indicates no such thing; this is a _style_ question, and modern usage differs between British-influenced and American-influenced style guides, which (respectively) place punctuation inside the quotes only if it belongs there and place punctuation inside the quotes all the time."

Others pointed out that the grammar rule doesn't apply here anyway. In a case like this, you aren't using the quote for its grammatical purpose but rather as a delimiter, much as you might use brackets such as [ ] or < >. You wouldn't place the comma inside the closing bracket, unless the reader is supposed to type the comma; therefore you don't place it inside the closing quotation mark.

Others suggested a variation on Geoff's solution. Instead of putting the literal text into the second column of a table, put it on a line by itself. This solution often requires slight rewording similar to that suggested by Geoff. Some writers also put the literal text in a different font, but I don't think this is necessary, unless the normal font does not distinguish clearly between 1 (the numeral one) and l (lower-case el).

Emphasizing the most important issues in your style guide

The March 12, 2001 issue of the online magazine Contentious had an excellent item on the need for in-house style guides for online (web) content, and what those style guides should include.

The author (Amy Gahran) argues, and I agree, that your choices on consistency items such as capitalisation and punctuation don't "matter nearly as much as how you shape and deliver your messages." I would add that although this is also true of printed materials, some of the requirements for online materials are sufficiently different that writers and editors may need extra guidance.

Ms Gahran goes on to list the important issues, many of which (for example, the components of audience analysis) will be familiar to experienced technical editors and writers but seem to have been missed by the developers of many websites.

Where have we heard this statement before? "If your overall approach to content does not work well, then getting all of your commas in the right place won't make much difference."

The full article is here: http://www.contentious.com/articles/010312-1.htm

The same issue of Contentious has an article on the components of online content, and why websites need editors involved right from the beginning of the project. http://www.contentious.com/articles/010312-3.htm

What style guide to use?

A reader asked:
"[We] produce a variety of publications... [We] generally use British English, unless the target audience ... uses American style English.

"I'm wondering what you ... use as a general reference work. I use the Chicago Manual of Style and the CBE manual for more scientific documents. A fellow editor here feels this is inconsistent. She feels that if we use British English, we shouldn't be using the Chicago Manual of Style. This doesn't make sense to me as probably more than 90% of what's in the Chicago applies to all documents, whether they're in British or American English. However, our policy is to use single quotes, rather than double, so this is a deviation from Chicago, but every publisher has its own house style."

I answered:
"I use different style guides depending on the project I'm working on, partly because (as in your case) some projects use British English and some use American English.

"A common technique for a department like yours is to choose one or more guides like the Chicago Manual, then create a brief (could be as short as one page) in-house supplement that lists any deviations from the main guide, such as the use of single quotes rather than double quotes. No style guide is likely to cover 100% of your needs; if Chicago covers 90%, I'd certainly continue using it, along with a house style sheet.

I have an article about style sheets here: http://www.jeanweber.com/howto/ed-style.htm

Results of poll on plain text or HTML newsletters

Last issue I asked whether you would prefer to receive this newsletter as plain text (as you do now) or in HTML, and I put a poll on the website so you could vote.

So far, 26 people have voted (out of more than 800 subscribers); 14 chose plain text, 7 chose HTML, and 5 said no preference. If you'd like to have your say, you can vote here: http://www.jeanweber.com/news/index.htm

(Advertisement)

Copies of "Website Indexing" now available from me

In issue 52 I mentioned a book titled Website Indexing by Glenda Browne and Jonathan Jermey, published in 2001 by a small press in Adelaide, South Australia. My review is here: http://www.jeanweber.com/books/webindex.htm

I now have some copies of this book for sale. Cheque/chck only. A$36.50 or US$20. Send to JH Weber, PO Box 640, Airlie Beach Qld 4802, Australia, AND e-mail me to say you've sent the check -- if I'm away from home, I may not get your check for weeks, but if I know you have sent it, I can mail the book to you.

(Advertisement)

I host this website on Server101

A few months ago I redesigned this website and moved it to a new web hosting company, which 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. Please note that I am now an affiliate of Server101, so please use this link if you are interested in learning more about them. http://www.server101.com/?AID=5123

(Advertisement)

The website your boss doesn't want you to know about!

http://www.quickinfo247.com/4148861/IEF

(Advertisement)

Books by Jean Hollis Weber

Taming Microsoft Word

Hot tips and cool tricks for business and technical documents. A quick reference for writers, editors, and others who need to use some of Word's more advanced features. More information here: http://www.jeanweber.com/books/tameword.htm

Editing Online Help

For students, writers, and editors who are developing online help for computer software, and for their managers and clients. Supplements tool-specific instruction by presenting the basics of help content developmen. More information here: http://www.jeanweber.com/books/olhbk.htm

Electronic Editing

A quick start guide for editing students, experienced editors making the switch from paper to online, and anyone who needs to write or edit electronically. More information here: http://www.jeanweber.com/books/e-edit.htm

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