Newsletter

Issue 25, 28 October 1999

ISSN 1442-8652

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

In this issue...

News: Late issue and WinWriters' 2000 conference
Feature article: The 4 (or 5, or 6) C's of effective communication
Tip: Using real or fake URLs in publications
Resource: Your web site -- design, marketing and maintenance
Subscription information

---

News: Late issue and WinWriters' 2000 conference

Yes, this newsletter is a week late. I spent most of last week in Sydney, where I attended the annual conference of the Australian Society for Technical Communication (NSW) Inc. and spoke at a meeting of the Women in Publishing group in Sydney (see item under "Resources" below). The highlight of the week was the official launch of my "Electronic Editing" book, held at the ASTC conference.

I am presenting a session titled "Usability testing for editors - is the help helpful?" at the WinWriters Online Help Conference, San Diego, March 5-9, 2000. I hope to have copies of my next book (working title "Editing online help") available at the conference. Registration for the conference starts November 1. For more information, see:

http://www.winwriters.com/ohc.htm

---

Feature article: The 4 (or 5, or 6) C's of effective communication

Back in March, a discussion on the Technical Writers' list centered on the C's of communication. Several lists were put forward. I found the differences interesting, particularly when compared to one list I have of a copyeditor's task.

List 1:

Clear
Correct
Concise
Complete
Consistent
 

List 2:

Clear
Correct
Concise
Complete
Courteous

(List 2 replaces "consistent" with "courteous." While I agree that "courteous" is a good quality for a document, I'm not entirely sure what is meant by that term, and I would not want to ignore consistency.)

 

List 3:

Clear
Concise
Complete
Consistent
Coherent
Coordinated

(Note that List 3 does not include "correct" or "accurate," but does introduce some worthy new qualities: coherent and coordinated. I'm expanding this list after the copyeditor's list.)

 

Copyeditor's list:

Correct (spelling, grammar, punctuation)
Accurate (dates, model numbers, quotations, references, hypertext links)
Consistent (word usage; design; color use; icons; etc.)
Complete (all the parts present, including all illustrations mentioned in the text; all hypertext links lead somewhere; that sort of thing -- does not mean "contains all possible information about the topic")

Expanded List 3

My thanks to whoever posted this to TECHWR-L. I extracted the list but did not keep the poster's contact information.

Clear

Your goal is to make what you write easy to read and understand.

• Use terms your readers understand.
• Write in plain language.
• Use strong verbs in the active voice.
• Where you have a choice, choose the simple over the complex.
• Use familiar words.

Concise

Include what people need to know, and keep nice-to-know information to a minimum.

• Use bullets wherever possible.
• Be brief.
• Write to inform, not impress.
• Use short, simple sentences.
• Avoid unnecessary words.
• Edit ruthlessly.

Consistent

Use the same terminology in all to avoid confusing the readers. For example, if you first use the word "type" to describe entering information on a computer, do not use the word "input" later in the procedure.

• Adopt the "Pick and stick" rule (choose terms, titles, style conventions etc. and stick to them).
• Avoid ambiguity.

Coherent

Organize your materials so they are easily understood.

• Use advanced organizers.
• Present information in a logical sequence (from the readers' point of view).
• Present the steps in a procedure in the order they are typically carried out.
• List all steps of one activity before beginning the next.

Coordinated

Consider whether your documents are coordinated:

• with all related areas or departments
• with other policies and operations
• so that all information arrives at the same time (for example, forms, disks, sales and service kits, promotional materials, or videos)
• for delivery of the right information to the right people at the right time, with the approval of all business partners

Complete

Include all the information needed to allow readers to effectively and knowledgeably complete their tasks (that is, ensure customer/reader expectations are met or exceeded).

I did like the admonition to "edit ruthlessly" in the discussion about conciseness!

---

Tip: Using real or fake URLs in publications

A discussion (on the TECHWR-L list) about using fake URLs in examples, or real URLs in references, included this exchange:

Geoff Hart ghart@videotron.ca:
If you're going to use a fake URL in a manual or printed publication, try out the URL first. Someone's bound to try it out (QED!), and you might be embarassed by what they find.

Mike Stockman stockman@jagunet.com:
Just for reference, there *is* an existing standard for using example domain names, in documentation or anywhere else. RFC2606 (found at http://www.faqs.org/rfcs/rfc2606.html among other places) says this:

"Abstract

"To reduce the likelihood of conflict and confusion, a few top level domain names are reserved for use in private testing, as examples in documentation, and the like. In addition, a few second level domain names reserved for use as examples are documented.
[snip]

"3. Reserved Example Second Level Domain Names

"The Internet Assigned Numbers Authority (IANA) also currently has the following second level domain names reserved which can be used as examples.

   example.com
   example.net
   example.org

--end of excerpt--"

Given that these are reserved, they can (and probably should) be used anywhere you want to provide a domain name example without worrying about where it will take the user. Presumably, variations on these domains are safe as well, such as prepending "www" or "ftp" onto any of them.

Eric J. Ray ejray@raycomm.com:
I'd strongly advise anyone publishing anything referencing URLs that you don't control to include a strong disclaimer. We [Eric and his wife Deborah] found, to our horror, that a previously reputable HTML-related resource that we referenced from multiple books turned into a porn site... the publisher got some rather strongly worded complaints, and we introduced a "all URLs verified at time of publication, but we take no responsibility for what's happened since" type disclaimer.

---

Resource: Your web site -- design, marketing and maintenance

I presented a paper to the Women in Publishing group in Sydney last week. It's a fairly general introduction to some of the issues to be considered when setting up a website for a small business such as a writer or editor. The costing information is, of course, specific to Australia.

I've put a PDF version of the paper here: http://www.jeanweber.com/ftp/wiptalk.pdf

---

© 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.

---