This diatribe was originally foisted upon a class of unmotivated and nearly illiterate university students. It was my job to attempt to teach them something about Unix and Linux, while also demanding, as a matter of school policy, that they upgrade their largely nonexistent writing skills.
If you write well, you will be able to do many things in life. If you cannot, you will find yourself correspondingly limited.
Therefore, writing well matters a great deal to me from both ends of the communications spectrum. I make an effort to write my best even in rapid-fire email exchanges.
Language is the primary tool of human thought. It is invariably true that a person who cannot write or speak effectively also cannot think clearly. Excuses such as “I’m a numbers guy,” or “I’m a programmer, not an English professor,” merely manifest the speaker’s desire to beg off the issue, and to mask fundamental intellectual shortcomings. In contrast, many of the most brilliant technical minds have been superlative writers. Donald Knuth, Douglas Hoffstadter, Richard M. Stallman, and Eric Raymond are just four that readily come to mind.
I refuse myself the luxury of such laziness, and wish that others who desire to communicate with me in writing would make the same effort to express themselves clearly in the full range of their writing, whatever form that might take.
Guidelines on Formatting in Plain Text
A great deal in the way of formatting can be
accomplished in plain text, even without markup. My
email messages always follow the principles I've
learned over the years.
joe> This is a quote of a message from Joe Blow,
joe> which is neatly indented with citation software.
sue> Persons who insist on using braindead tools will
sue> produce work that looks like it was written by
sue> braindead authors. Your work can be only as good
sue> as the tools you use will allow you to be.
Set a narrow margin width. My practice is to wrap
paragraphs at 55 characters in email, and 60, 65, or 70
characters for other things, depending on what it is.
Narrow columns of text are much easier to read than
wide ones, and easier to quote in email as well.
Here are some other tips:
o *Do* use line breaks. No one likes to read email or
anything else where the lines extend forever.
o Put blank lines between paragraphs.
o Bullet lists can be created to look like this one,
using an "o" character to represent the bullet.
Notice how second and following lines indent.
- Bullet lists can even be nested.
- You can choose another character such as a minus
sign for the bullet in sublists.
o Emphasis (normally indicated by *italics*), can be
emulated by putting text between *asterisks*.
o When sending email, always turn off HTML unless it is
needed for some special purpose. HTML email is
*evil.* It's usually ugly, it's hard to quote, and it
is loaded with security holes. Many recipients *hate*
HTML email (including me), and many mail lists ban
it.
A Centered Main Title
=====================
Main titles can be centered and indicated as primary
points with an equal sign underline.
Subheadings Are Underlined
--------------------------
A subheading can look like the one that precedes this
paragraph. If you have something you would like to
quote, it can be indented.
Any Web developer who is unconcerned about browser
compatibility should be shot. -- Dwight Newton[1]
[1] My brother. Because there is no bottom of the page
in this type text, my custom is usually to put a
footnote immediately after the paragraph where
it appears.
Sometimes we have need for hanging paragraphs, as in a
glossary list:
SHELL The SHELL variable usually is set to the name of
your login shell.
TERM The TERM variable is set to the type of
terminal you are using. In a graphics environment
it is often set to xterm, but on real character
terminals is it often vt100.
HOME The HOME variable is set to your login
directory. Therefore, when you execute a command
such as:
ls -l $HOME
it shows the files in that directory regardless of
what your current directory is.
Finally, tables can generally be created without too
much trouble, and in most cases look just fine.[2]
Sun Mon Tue Wed Thu Fri Sat
YY YY NN YY [55.82]
NN YY YY YY YY YY NN [21.83]
YY YY YY YY YY NN YY [47.30] Sun Mon Tue Wed Thu Fri Sat
YY 20 21 22 23 24 25 {35} 10 2w 5 10k 5 2 5
26 27 28 29 30 31 {52} R 40 2w 3 5 2 DA
nn:KK mm.dd h:mm:ss.dd mm:ss.dd mm.dd comments
----- ----- ---------- -------- ----- --------
01: 5.02 0:52:23.00 10:26.11 37.82 22
02:WQ 3.08 0:42:07.41 13:39.95 30.86 22; w48
03:
04:Q 34.96 7:06:39.00 12:12.17 55.82 22
06:E 2.03 0:28:05.87 13:52.29 52.04 22; w15
07: 3.08 0:31:12.00 10:07.32 22; w20
08:W 4.05 0:54:10.89 13:22.46 47.20 22
[2] Of course, this is all much easier to do with an
editor like Emacs!
