Home » Uncategorized » Writing clearly in a plaintext world

Writing clearly in a plaintext world

===
Writing clearly in a plain text world
===

In my line of work, there are alot of emails flying around. We do tech
support, which involves writing to customers, writing to colleagues
with whom we're on friendly terms, and other people in the organization
with whom we are less familiar.

Every email sent is ideally logged against a case, in a system that
only manipulates plain text: so colours and formatting are always lost
in the archival version. Welcome to the world of plain text, where there
is no style, no formatting - only text. It is in plain text that I
write this blog post today.

Most of the time in these emails, the trail of thought can be picked up
easily enough. However, when taking over a case from a colleague, or
when for some reason someone switches the format to plain text, a lot
of the meaning is lost, as the meaning was closely tied to the
formatting (coulours, underlines, italics, indentation, tables, etc etc
etc) Email is not publishing, one *must* expect the look and flow of
the text to change frequently, and its structure and meaning must be
able to resist the most common changes.

So what practices guarantee that such information will not be lost
somewhere down the line, allowing email trails to remain readable?
Here's some tips:

===
Write clearly
===

Some things to NOT do in the world of email:

-do not write everything in one line. Make use of paragraphs: in plain
text, this means hitting the return key TWICE

-do not use colour to denote responses. Colour can be lost. One of my
pet hates is "my responses are below in [colour]", especially when I
receive it from someone else who forwarded that message in plain text.

-do not use abbreviations, other than "e.g.", "i.e." and "etc"

-do not use capitals unless there is call for it. There are other ways
of emphasizing text OTHER THAN LOOK LIKE YOU'RE SHOUTING AT YOUR
CORRESPONDENT
  -->tip: it's considered extremely rude in most Internet communities



Some other things to consider:

-make use of punctuation - properly placed commas, dashes, semi-colons
and colons are all helpful in the right context.

-do not fear using words slightly redundantly, especially when a
subject is getting complicated. Mention an item in your phrase, an if
afterwards you want to talk about the item, repeat the name of the item.
Only use "it" or "that" when there is absolutely no possible ambiguity.

-keep the phrases as simple as possible. Emails should not be treated
as epistles, but as technical documents, whatever the subject. They
must inform, and not say anything more than you intend

-rather than including an image in the flow of the text, save it as a
file and attach it to the mail, saying "see attachment picture.jpg" or
"c@ picture.jpg"


The following are some stylistic conventions harking back to the days
when plain text was the only option. It is still true today when
writing on a number internet forums, comments under blog posts, etc

===
Underlines, bold and italics
===

This is _underlined_ text

This is /italic/ text

This is *bold* text

So when you really, *really* want to emphasize something, use /special
characters/ to replace the formatting. Only use it to surround no more
than one or two words. Only emphasize what is _necessary_

===
Quoting
===

If you're going to quote more than a full sentence, it is better to
put the text in a block quote.

/==
This is a block quote. It is recommended to use it when there is a
significant amount of text.

There may even be several paragraphs.
==/

In this way you quote from documents and other exterior sources.

If you are going to quote from someone else who previously wrote in
the same thread, use ">" characters at the start
of each line

> These lines were forwarded
> from a previous message

In that way, it is possible to immediately identify quoted messages,
and it is not lost when the colour coding is gone.

===
Other structures
===

It is good practice to have well structured text, but some of the
structure tools used in rich text editors get
completely lost in plain text.

Use text-based bullet points instead of automatic ones.

# like so
# and so
# and so, too

Or maybe you prefer
-this kind
-the dash
-less garish

###
This is under a new section, separated from the above, but still under
the same title.

And finally, all the way through this note, I have been using the
encapsulating "===" around titles. You should do so too.

=============== Thank you for reading. Now start writing in a cleaner fashion with your new knowledge.

Posted in Uncategorized and tagged as , ,

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.