Rant on Writing

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!