Skip navigation

This posting is currently being edited and expanded.

  1. Use simpler words whenever possible. see last paragraph.
  2. Avoid repeating yourself.
  3. Don’t use too many “aside” comments.

    If you have to make something into an “aside” comment, then perhaps it doesn’t belong this piece of writing at all.

    If every paragraph of your writing seems to have an “aside” comment in it, then your writing will be seen as “all over the place,” or “difficult to follow,” even if your writing appears “coherent,” and “clear” to you when you yourself read it.

    If you use too many aside comments, then your writing might even appear “boring” to some readers, simply because you take a little too long to get to your point. In this case, the reader isn’t interested in the asides, even if you find them very interesting. The reader is impatient, especially in technical writing, and wants to see you make your point as quickly as possible.

  4. Avoid using synonyms, or sets of words that mean the same thing, in a single sentence.

    This next quotation is from Keisler’s free calculus text.

    A second way to visualize a function is by drawing its graph. The graph of a real function f of one variable is the set of all points P(x,y) in the plane such that y = f(x). To draw the graph, we plot the value of x on the horizontal, or x-axis and the value of f(x) on the vertical, or y-axis.

    Why doesn’t he just write:

    A second way to visualize a function is by drawing its graph. The graph of a function f is the set of all points in the plane that satisfy y = f(x).

    To draw the graph, we plot the value of x on the x-axis and the value of f(x) on the y-axis.

    * Notice how I removed the words “on the horizontal,”. Really the thing here is more words that say the same thing = slower reading.

    Its kind of like writing: “The dog wagged, or moved from side-to-side, his tail.”

    If I need to define “wagged” for my reader, then I should do so either in the sentence immediately preceeding the sentence that uses the word “wagged”, or in the sentence immediately following the sentence that uses the word “wagged”.

    For example:
    “To wag one’s tail means to move it from side-to-side. And the dog was wagging his tail.”

    Or:
    “The dog was wagging his tail. To wag one’s tail means to move it from side-to-side.”

    Now if we did that with Keisler’s sentence:

    “To draw the graph, we plot the value of x on the x-axis and the value of f(x) on the y-axis. The x-axis is the horizontal axis and the y-axis is the vertical axis.”

    It looks silly because the fact that “The x-axis is the horizontal axis” should be bleeding obvious. So, that’s why “the horizontal, or” needs to be removed from the original sentence. It adds no meaning or value and bogs the reader down.

  5. Avoid repeating yourself.
  6. Make new paragraphs as often as possible. Technical writing should be written like common newspaper articles are written. One simple thought to a paragraph.

    When in doubt, create a new paragraph.

  7. Use parenthetical commentary only when absolutely necessary to retain correctness, not to show off how smart you are or how you have special sensitivity to some nuance that others do not. “Others” do not care, really.

    Nothing throws a student off or interrupts the flow (or “languistic motion characteristic”) of writing like unnecessary parenthetical commentary.

    *I just made up the term “languistic motion characteristic” to prove the point here –

    Here’s a good example of when TO use it:

    “For example, if you choose the vp30 profile, you can write a Cg vertex program that loop a varying (non-constant) number of times.”

  8. Every technical writer should be forced to read Strunk and White before being allowed to wield the pen.
  9. Avoid using the word “which”. Use “that” instead.

    The phenomenon which is responsible for this is the same phenomenom which is responsible for lightening.
    The phenomenon that is responsible for this is the same phenomenom that is responsible for lightening.

I realize this list is repetitive but I’m really tired now and need to sleep.

Advertisements

One Comment

  1. I especially like the Strunk and White statement. Very nice!


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: