Some notes on how to use email and mailing lists
How to get assistance, answers, help
Off-topic postings
Proper use of subject lines
How to quote previous comments
Large emails, large attachments
Unnecessary information
Line length
Data formats
Including configurations and other files
Bad grammar, spelling, punctuation
Some other resources
How to get assistance, answers, help
The first step in solving a problem is clearly identifying it.
Good reports are much easier to give good answers to.
Accurate reporting of the original problem can help with producing
an exact diagnosis. (Inaccurate reporting may result
in a response that answers a different or unrelated problem.)
You may want to try using script(1) to show exactly what happened.
Often in many cases, being careful to get the report
right in the first place leads to a sudden awareness of the
mistake that was made. Consider following these steps:
- Have you read the documentation?
- Have your read the appropriate FAQ?
- Have your read the manual pages?
- Have you searched the mailing list archives?
- Have you searched Usenet archives?
- have you searched the web (google and altavista)?
- What, exactly, fails?
- What steps did you attempt to resolve it?
- What do your log files show?
- Post details of what went wrong.
- What error(s) did you get?
- What steps are you taking to test?
- Show us exactly what happened.
- If applicable, what does the software's debugging show?
- Don't say "it didn't work". Show how it didn't work.
- Don't make the readers guess.
Off-topic postings
People subscribe to specific mailing lists to discuss specific topics.
You will probably have a better audience and
you will probably find better answers if you post to a forum that is
appropriate for your comments and/or questions.
Most people don't have the time to waste reading topics that don't interest
them -- that is why they they are subscribed to a focused mailing list.
Proper use of subject lines
The subject line should accurately describe the topic you are discussing.
In addition, don't use your subject line as your main question or
statement and then fail to repeat (or rephrase) it in the body of the message.
Often, messages are simply skipped due to an inaccurate or uninteresting
subject line. Sell your email by grabbing the reader's attention with
an honest subject line.
Bad subject line examples:
- "Help!!!" -- what or why do you need help?
- "Problem booting" -- too vague, give more details
- "Webserver has security flaw" -- what webserver? What version? What type
of flaw?
A prepending "Re:" or "AW:" in a subject line means it is a reply; it was
not the
original posting, but an answer or comments about the previous message.
If you are replying to message, be sure to have your mail client prepend
an indication that it is a reply.
How to quote previous comments
When replying to another email, be sure to chop out all superfluous
information. Remove any added junk, like signatures, mailing list footers,
advertisements, and any other comments that don't relate to what you are
replying about.
Do keep enough context in the reply to make sure that the readers know where
you are coming from and how it relates.
If replying to an email that contains other replies, be double-sure that
the attribution for all the comments is correct. Do not make
it appear that some comments were said by the wrong person.
Some email clients attribute text by saying "you wrote". Do not use a
vague pronoun -- make sure your mail client intelligently uses the real
name or email address so it will be appropriately attributed.
A variety of techniques exist for quoting previous postings. Some ideas
include indenting the original comments or indenting your comments.
A commonly-used idea is to have a "> " placed before the original lines;
most mail clients can do this for you when you select "reply".
(Again be sure that the comments are correctly attributed.)
It is often
considered a good idea to place your comments directly after the paragraph or
question it applies to.
Please be sure to place at least one blank line between your paragraphs to
separate your comments from the original. (Do not place your comments
abruptly next to someone elses.)
Large emails, large attachments
Don't email thousand line messages, huge tarballs, complete
ktrace or coredump files, giant images, or other super large
postings to a mailing list.
This wastes valuable resources -- especially when the same large file is
sent to thousands of recipients. In addition, many mailing list readers
often pay for their downloads. Thirdly, large emails may take a long time to
download (consider 14.4 modems).
Instead, put the file (or files) on a web or ftp server somewhere,
and then simply email URL. Or send a description of the huge file(s)
and offer to email the big file(s) to individuals who request a copy.
This applies to binary as well as text messages.
Unnecessary information
When replying to any message, delete the majority
of the original. Retain just enough to maintain context
for the reader.
For example, do not have a single-line reply that also includes a previous
20,000-line message. It is also probably a waste to have a single-line
reply that also includes a 20-line message.
Length of lines
It is often considered good advice to send lines that don't exceed over 65 to
75 characters per line.
Some mail clients do not wrap the long lines (very well or at all), so it
is hard to read.
Some mail clients have problems quoting long lines when replying.
Data formats
Please consider using standard ASCII, plain text for your emails.
many email users read their email with mail clients that can't
properly convert messages sent in HTML, Microsoft Word document, etc.
In addition, when you don't use plain text for the your messages, then you
may also be wasting valuable bandwidth and time.
Also, many email users don't own (or have installed) the tools to
read or convert formats created by commercial (and often expensive)
or proprietary software.
(See link below about this.)
Including configurations and other files
The following are some ideas to consider
when including configurations to help research problems or to provide
examples.
- Make sure it is easy for the mailing list readers to use and read.
- If the configuration is short, simply paste/include it within the body
of the message, so it doesn't have to be viewed/manipulated
as an inconvenient attachement. (Often, readers will simply delete
messages that are not easy to read.)
- If very long, maybe consider stripping all the comments. For example,
a 1500 line Apache or Exim configuration, might only be 20 lines of real
configurations; and the Apache or Exim professionals probably don't
need to wade through all the comments just to see the issues with the
configurations. (Again, make it easy for others to help you.)
- If your situation only involves a few lines of configuration, then
only include the applicable lines. Most of the time, you do not need to
provide the entire configuration file. For example, if your email is
about a certain device configuration, don't provide the entire dmesg output,
but only the lines that are applicable.
- Usually it is appropriate to simple paste in several separate configuration
file within the body of one email message. Be sure to properly explain
what each configuration is for. (This is easier to quickly read than trying to
save and open several attachements.)
Also,be sure to follow the suggestions in the other sections of this document
about attachements, size of emails, etc.
Bad grammar, spelling, punctuation
Often users of mailing lists have native languages different from
the majority of the readers. Not everyone has the same education
and background.
If your grammar, spelling and/or punctuation skills are not perfect
for the commonly-used language, then that is okay. Try to use a dictionary
and spelling checker first, if available or possible.
Also, be sure to not use all capital letters. DO NOT USE ALL CAPS!
It is often hard to read and is used for indicating emphasis (or shouting).
Here are some hints:
- Start sentences with a capital letter.
- Be sure to end sentences with a period.
- Separate different unrelated comments or long-winded sentences
with a blank line; in other words: start a new paragraph often.
Some other resources
This page last updated on:
Tue Jun 16 14:08:46 EDT 2009