Back to Wiki Homepage

Secretchronicles Wiki

Mailing List Etiquette

The TSC project uses Mailing Lists for coordination of the development process. Mailing Lists basically work like forums, but completely over email (You can also respond on the Web UI). This allows everyone to get the most recent news easily and directly reply from their inbox, plus nice threaded views, killfiles, and all the nice features good email clients (= non-web email clients) support.

This page lists the things you need to know to properly work with a mailinglist. Most of this should be intuitive, but just in case it is spelled out here.

General

A mailinglist is managed by a mailinglist software that receives the emails sent to the list address (e.g. tsc-devel@lists.secretchronicles.org) and sends a copy of that email to every subscriber of the mailinglist. At TSC, we use GNU Mailman as the mailinglist software.

This means that you address your messages only to the mailinglist address, not to each of the subscribers. That’d be impossible with a large mailinglist anyway. Let the mailinglist software handle that for you.

Mailinglists generally require subscription so that they are not spammed by anonymous addresses. For the TSC mailinglists, you can find subscription instructions here. Similaryly, you need to unsubscribe from a mailinglist again if you want no further messages from the mailinglist.

It is highly recommended to use an email client (or even better server) that supports email filtering. Your main inbox will quickly get cluttered if you follow more than one mailinglist, so you are way better off to automatically have your mail software place the mailinglist messages into a separate folder before you even see them. This will keep your INBOX clean and collect all mailinglist-sent messages in one folder. Another tip is to use a threaded view so that you can see who replied to whom during the course of a thread. Generally badly usable for mailinglists are web-based mail clients, with GMail being a possible exception.

Guidelines

Courtesy Copies

First: Everybody subscribed to the list gets all messages sent to the list. Thus, don’t include an entire message of someone else in your post to the mailinglist (this is sometimes ironically called a “courtesy copy”). Nobody wants to read everything twice. Time is spare.

Plaintext mail

Do not use HTML email when posting to a mailinglist. Mailinglists often get archived on the web, and HTML messages copied as-is to a public web archive make for a wonderful security vulnerability as it allows the attacker to hijack the archive website. Therefore mailinglist archives will ignore HTML parts of emails or escape them (making them look very unappealing). The TSC list archives do that also.

Then, HTML email is hard to work with. Handling it in the email client is cumbersome (autoquote function will not work correctly for example), and people using text-only email clients (many programmers and admins do!) can’t even read HTML messages. HTML email is bloated. Most HTML-only mail is spam, to such a degree that one can set up a pretty efficient mail filter that automatically flags every HTML email as spam, and there are people doing this. Don’t let them qualify your important content as spam.

Line breaking

Use an email client that automatically inserts line breaks into your paragraphs. No line should be longer than 80 characters, which is very hard to read already. Better keep line lengths between 60-70 characters. Good email clients do that automatically, you don’t need to do that by hand. Really.

Not breaking your lines will result in something like this in a good number of email clients that really looks bad and you really can’t read that. Wasn’t that hard to read?

Alternatively, some email clients will break it li
ke this which is also bad and hard to read. You do
’nt want that either.

Quoting

In plaintext emails one quotes with > or | signs; good email clients will highlight such parts in a different color. Use quotations where appropriate and do not quote the entire message (see “courtesy copies” above).

Looks like this:

> I think we should do it like this: ...

I don’t think this is a good idea.

> Some other important stuff.

Probably you should...

Notice how one only quotes those parts one actually replies to. Quotes have a function. Don’t quote things that are not relevant to your message. It is absolutely fine to not quote anything from a previous message if you bring up completely new points.

If you need nested quotes (use sparingly), you can use one > per indentation, e.g.:

>> Foo
> Bar
Baz

Top Posting

“Top-posting” is the act of starting your reply at the top of the email, and a large courtesy copy at the bottom. This destroys the flow of read (and courtesy copies are annoying anyway). The maximum you can post at the top of an email is a greeting. This is wrong:

Hi there,

this is my important reply.

> Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
> nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam
> erat, sed diam voluptua. At vero eos et accusam et justo duo
> dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
> sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit
> amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
> invidunt ut labore et dolore magna aliquyam erat, sed diam
> voluptua. At vero eos et accusam et justo duo dolores et ea
> rebum. Stet clita kasd gubergren, no sea takimata sanctus est
> Lorem ipsum dolor sit amet.
> Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam
> nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam
> erat, sed diam voluptua. At vero eos et accusam et justo duo
> dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
> sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit
> amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
> invidunt ut labore et dolore magna aliquyam erat, sed diam
> voluptua. At vero eos et accusam et justo duo dolores et ea
> rebum. Stet clita kasd gubergren, no sea takimata sanctus est
> Lorem ipsum dolor sit amet.

Lg
foo

This is correct:

Hi there,

> Lorem ipsum dolor sit amet

This is my important reply.

Lg
foo

Much nicer to read, isn’t it?

Emphasis

If you can’t use your <blink> and <marquee> HTML tags, how do you emphasise in a plaintext-only message? Like this:


  /this is italic/       (= mild emphasis)
  *this is bold*         (= strong emphasis)
  **this is thick bold** (= very strong emphasis)
  _this is underlined_   (= what do you need that for?)

A good email client will recognise these and format the text accordingly.

Unicode

Plaintext email does not mean ASCII-only email. Use Unicode freely and often, it enriches the Internet in many useful ways.

Attachments

Plaintext email also does not mean “stash everything into the mail body”. Attachments (aka MIME parts) are the usual and recommended way to send larger assets with your messages (for example large log files or binary files). A log file adds no value to the text of your message, use an attachment to transmit it.

On the other hand, email is no truck. Do not sent things by email, not even as an attachment, that exceed 10 MiB in size. Upload large files to a server (for example, to your personal server if you have one, or a storage account of some sort) and instead share a link in your email to the mailinglist. The TSC mailinglists will reject huge emails.

Subject

Use a meaningful subject for your message. “Help”, “Newbie”, etc. conveys no information about your message. It is likely that it will get ignored.

Replying

Reply on the mailinglist. Every good email client (you know, usually this means non-web clients) provide a separate button “reply to list”. Use that one when replying to a mailinglist email. If you don’t do that, you send your reply only to the person who wrote the post, i.e. you create a so-called “personal message” (PM for short). The receiver will get annoyed if he sees you reply only to him and not to the general public. Pro tip: Check the “To:” field before you hit the “send” button. It must contain the mailinglist address, and not the address of the post writer.

When replying, reply to the exact message you are referring to. Mails use a hidden header field called the “Message-ID” that (good) mail clients use to display multiple mails in a threaded view; on reply, your mail client copies this Message-ID into a new hidden header field called “References” which is then in turn used by the receiving mail client for ordering. If you reply to the wrong message, those mail clients will sort in your message under that wrong one, causing confusion. If you don’t want to refer to a specific message in the thread, but want to bring up something totally new that is still on topic in that specific thread, reply to the initial post of the thread.

Do not reply to existing messages for starting a new thread. This is known as “thread hijacking” and completely disturbs the conversation flow. You risk being banned from the ML quickly if you do that. Send a new message using your mail client’s “compose message” functionality for new topics.

Signatures

Use of signatures is fine. Many people use them for showing information like a GPG key ID or some famous quote. Your email signature is part of your personality, an aspect of self-expression. If using signatures, use the standard signature separator -- (note the space at the end!). Email clients and web archives will notice this and display it in a slightly different colour, allow hiding it, or even cut it off entirely depending on the gusto of the user.

Keep signatures at a maximum of five to six lines. Anything longer than four lines usually looks suspicious, unless of course you use beautiful ASCII art.

Crossposting

A “crosspost” is a post sent to multiple mailinglists at once. Crossposting for the sake of getting an answer more quickly is frowned upon; be patient and wait some time before you try again somewhere else. Doing a crosspost is only appropriate if the topic in question affects multiple communities at once. For instance, you sometimes see crossposts between the GCC developers’ mailinglist and the MinGW mailinglist when some MinGW user discovers a MinGW-specific bug in GCC.

Rule of thumb: If in doubt, do not crosspost.

Referencing

From time to time you want to reference older messages from earlier threads.

There are other ways to do this, but the recomended way, which is also the easiest way for everyone else to read, is to go to the Mailing List Web Interface, find the post you are referring to, then click the little "chain" icon it the upper right-hand corner, as shown in this screenshot. You are not required to have a actual account to view, subscribe or create links to the Mailing List.
Screenshot 1

Inline links

Usually it’s best to use footnotes for hyperlinks so that they don’t clutter the main message text. Compare:

I found a super cool website (https://secretchronicles.org/en/screenshots/)
that I encourage you to look on. The game discussed there is unique and I really
couldn’t imagine anything better.

vs.

I found a super cool website[1] that I encourage you to look on.
The game discussed there is unique and I really couldn’t imagine
anything better.

[1]: https://secretchronicles.org/en/screenshots/

The latter version doesn’t disrupt text flow, whereas the former makes you search for the continuation of the sentence. The link is not part of the text, and thus it shouldn’t be part of it.

Some people prefer Unicode footnote numbers. That’s also okay:

I found a super cool website¹ that I encourage you to look on.
The game discussed there is unique and I really couldn’t imagine
anything better.

¹ https://secretchronicles.org/en/screenshots/

Language

In your writing, show you are an educated and civil person. Use proper orthography and proper language. Avoid abbreviations like “ur” instead of “your”, “u” instead of “you”, etc. Not everybody speaks English as firm as you, and it makes you look childish. A mailinglist is a serious medium, not an average Facebook page. Use your email client’s spell checker.

You can use common abbrevations like “IMHO” or “ASAP” if you want, but avoiding them also looks still better. After all, you wouldn’t write those in a real letter, would you?

Do not write entire messages in capital letters. Capital letters are commonly perceived as shouting, and nobody wants to speak to persons who are shouting all day long.

Conclusion

If you use a proper e-mail client, then most of the above is fulfilled automatically for you. With rare exceptions, web-based email clients are pretty much unusable with regard to mailinglist etiquete, and for that matter, they’re pretty much unusable for any serious emailing, because a lot of the above is not at all specific to mailinglists. It is just that people reading and writing on mailinglists are email power-users that will get annoyed if they repeatedly get unreadable messages. Thus, install one of the email clients listed below.

If this list looks overwhelming to you, it isn’t. One gets used to these rules pretty quickly, because practise has proven they are useful. It makes email so much easier to read if they are properly followed. Also, nobody will yell on you if you accidentally violate one or multiple rules of this document one or even a few times. People will get annoyed if you repeatedly break these rules, especially if the problem with your message was pointed out earlier.

Good email clients

The email clients listed here, if used properly, will format messages according to the above rules. Please add to this list!

Known bad email clients

The email clients listed here are unusable in their default configuration. They will violate one or multiple of the above rules. Please add to this list!

  • MS Outlook
  • MS Outlook Express
  • Most web-based email clients.
ssets