Technical writing

It is important to remember that even though technical writing aims to communicate ideas precisely and unambiguously, such writing is still ultimately read by human beings and not computers. Readers of technical writing already have to struggle with challenging ideas, and it is up to the writers to make their writing as approachable and clear as possible.

Use words between mathematical symbols. For example, instead of “Consider {A_{mn}}, {n < m}”, use “Consider {A_{mn}} where {n < m}”. This serves to delimit mathematical expressions and avoid confusion.

Consider using words instead of symbols to express simple ideas. For example, instead of “Take {m, n \in \mathbb{Z}}”, consider using “Take integers {m} and {n}”. The goal is to avoid burying the reader in a morass of unnecessary symbols and notation.

Avoid unnecessary symbols and abbreviations. Instead of using {\therefore}, {\forall}, {\exists}, write them out in words! It is easier to read “for every {\epsilon > 0} there exists {\delta > 0} …” than “{\forall \epsilon > 0}, {\exists \delta > 0} …”

Write in complete sentences. Consider replacing each mathematical expression with some filler word, like “blah”. Is each sentence still complete? Still properly punctuated? Using mathematical symbols does not absolve the writer from the rules of grammar. If a sentence ends with a displayed math expression, use a period! For example, we can define

\displaystyle  |x| = \begin{cases} x & x \ge 0 \\ -x & x < 0. \end{cases}

Explain with words. It is often tempting to write pages of formulas and calculations and leave the reader to fend for himself while working through those computations. It is much nicer to the reader, however, to include some running commentary explaining what is being done.

Avoid walls of text. Nobody likes working through a dense argument that is one massive paragraph. Use paragraph breaks to give the reader some space to reflect on what’s been said so far. Use displayed equations to make them more readable, more visible, and simply as a way to break a paragraph into more manageable pieces.

Don’t be afraid to be redundant. It often makes things clearer to say the same thing in both words and symbols. For example, which definition of an open set is easier to read: “Every point {x \in X} has some neighborhood {B_\delta(x)} of radius {\delta > 0} around {x} such that {B_\delta(x) \subset X}” or “For all {x \in X} there exists {\delta > 0} such that {B_\delta(x) \subset X}”? They carry the same content, but in the first, the reader can focus on the concepts presented by the text, while in the other, the reader needs to translate from mathematical symbols into a more humanly parsable form.

Each theorem, lemma, corollary, definition should be self-contained. When scanning through a paper, its confusing to see

Theorem {f(x)} is a continuous but nowhere differentiable function.

Much better is to see “Let {f(x)} be as defined above in Definition 1.3. Then {f(x)} is continuous but nowhere differentiable.” Alternatively,

Theorem Let {f(x) = \sum_{n=0}^\infty a^n \cos(b^n \pi x)} where {b} is a positive odd integer, {0 < a < 1}, and {ab > 1 + \frac32 \pi}. Then {f(x)} is continuous but nowhere differentiable.

Give motivation and talk about the big picture. It is easy to blithely jump from one lemma to the next, giving clear and rigorous proofs of each lemma but losing sight of the reasoning behind those jumps. Before a chain of arguments and ideas, it helps to spend a paragraph talking about the big picture: Where is this argument leading? What’s the goal? Is there some intuitive picture or motivating example? All of this might be extremely clear for the writer, especially if he worked all of the details out on his own; for the reader, however, finding motivation and intuition often requires gaining a deep understanding of the topics under discussion. It only takes a few words to make everything much clearer.

Use clear formatting. Use section headings and appropriately space and align equations. This helps to communicate the structure of a paper. This is the subject of my next post.

For more on technical writing, see Knuth’s notes on mathematical writing.

Advertisements

One response to “Technical writing

  1. Pingback: Eighth Linkfest

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: