TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:what makes a good post From:Miki Magyar <MDM0857 -at- MCDATA -dot- COM> Date:Mon, 21 Dec 1998 15:08:45 -0700
Talkiong about Mike Huber's respone to Eric's post last week, I suggested that although "The
problem is BAD DOCUMENTATION", we still need the details of how to do it. Hmmm.... take your own good advice, Miki. Don't just say what's wrong, offer a suggestion about how to make it better. So herewith, my first hit at the how-to-do-it-right list. I'll be interested to see what additions and corrections you make.
Attributes of a really good post to TECHWR_L:
One that asks a question -
indicates in the first few sentences that the poster has done the homework of looking in references, searching the archives, asking SMEs, or whatever is appropriate.
puts ʽquery:ʼ or ʽ?ʼ as the first thing in the subject line, and identifies it well enough so someone searching the archives would find it.
clearly states the problem and its context, with enough background so that someone who has the information to answer the question will understand what question is being asked.
does not include a lot of history, personal anguish, angry rants, or other irrelevant stuff (except maybe a little bit at the end, if itʼs been a really horrible day).
supplies an off-list address for responses.
summarizes responses to the list if and only if someone asks.
says ʽthank youʼ.
One that answers a question -
repeats or summarizes the question - enough to identify whatʼs being answered. Does not re-post the whole query!
summarizes the answer in the first few paragraphs.
expands on the summary enough to be useful to someone who understands the question, but offers an off-list address or web site for more details.
assumes that the poster is intelligent but ignorant, and not stupid or lazy.
if appropriate, links the specific response to a more general issue of tech writing.
All posts -
has been spell-checked and re-read before posting.
has referred to the guidelines for appropriate topics and ground rules.
uses <snips> or a summary for context, not the entire text of someone elseʼs post.
makes a point, clearly, intelligently, and with regard to the amazing variety of people who comprise The List.
includes an e-mail address in the sig line.
adds something new and interesting to the discussion.
