Tips for Graduate Writing: Details

Tools

First and foremost, for technical writing use LaTeX. For equations, figures, and references, there's nothing better. Whatever you do, don't use Microsoft Word--it's hideous for technical writing. Yes, there's a learning curve for LaTeX, but once you're past it, you'll appreciate what it can do for you.

Syntax and Punctuation

I strongly recommend you get a copy of Strunk and White (also available online) or another good reference for grammar and punctuation. English, like programming languages, has a grammar. Use it. Just as using incorrect grammar can cause your compiler to go, "Huh?" (or even worse, think it knows what you meant when you meant something else), the same is true for using English to convey your message to your reader.

Figures

In proper writing, figures have a particular structure:

A noun or noun phrase that labels the figure, such as "Comparison of methods A and B", "Results for the 'peppers' image", etc. Properly speaking, this is the "caption". Think of it like a headline.
Additional text that explains the content of the figure (if necessary). Properly speaking, this is called the "legend". The legend can be a useful way to describe to the reader what they should be seeing.

LaTeX only has a single \caption tag, but try to keep this structure in mind when using it to label your figures. Here's an example:

\begin{figure}
  \includegraphics{...}
  \caption{Example Jabberwocky.  Notice how mimzy are the borogroves (left) 
           while the momraths outgrabe (right).}
  \label{fig:example}
\end{figure}

In many cases, you may want only the caption (label) to go in the List of Figures in the frontmatter, while you want both the caption and legend in the labeled figure. To do this, LaTeX has a "short caption" option on the \caption tag that allows you to specify the text that goes in the List of Figures, independent of what you actually put in the caption of the figure. For example,

\begin{figure}
  \includegraphics{...}
  \caption[Example Jabberwocky]{Example Jabberwocky.  Notice how mimzy 
           are the borogroves (left) while the momraths outgrabe (right).}
  \label{fig:example}
\end{figure}

When writing the explanatory legends, try to avoid simply labeling the subfigures: "(a) shows..., (b) shows...", etc. Instead try to label each subfigure directly. (The subfigure package is useful for this.) Then when describing the subfigures then, again try to tell a story with them: "When method A is applied to the original image~(a), it first calculates the Walrus~(b), then the Carpenter~(c). Eventually, it converges when they've eaten every one~(d)." Notice the judicious use of non-breaking spaces to avoid awkward breaks before the parenthetic references to the subfigures.

References

Use BibTeX. For a researcher, it's your best citation friend.

Advantages of BibTeX:

You can keep all of your references in one place, and cite them as needed.
You never have to worry about looking up how to properly format citations.
Reformatting to different formatting specifications is easy.

Some tips when using BibTeX:

BibTeX automatically uses the correct case when formatting your citations, but occasionally it goes wrong. In particular, it can have problems with acronyms or other cases of unusual capitalization. To avoid this, BibTeX takes anything you have in quotation marks or braces as literals and won't change the capitalization. For example,

title = "A study of {BYU}"

will keep the capitalization of BYU at is should be.

Many journals and conference proceedings will use numbers for citations.They do so mainly because it is the most compact in terms of space used. However, using the author name(s) and year makes it more convenient for a reader familiar with the literature. (They don't have to flip to the reference section to know what paper you're referring to.) Consider using the natbib package for citations.

Some Common Errors

That vs. Which

"That" is used to specify which one of something you are interested. "Which" is added almost parenthetically to add more information about something. For example, "the ball that is blue" refers to a specific ball: the blue one. On the other hand, "the ball, which is blue" refers to an unspecified ball, with the additional information that the ball is blue.

Tip: if you can leave the part following "that" or "which" out without changing your meaning, you should use "which"; otherwise, use "that". Also, "which" is almost always preceded by a comma since the clause is added separately (independently). If the comma makes sense there, so does "which". If not, and it breaks the single noun phrase awkwardly, it should probably be "that".

When you've finished writing, go on what an old writing professor of mine called a "which hunt". Use your word processor to check each occurrence of "which" to see if you should have used "that".

Et al.

You'll sometimes mistakenly see the phrase "et al." (which is used to indicate "and others" in citations) typed as "et. al." This is incorrect. "Et al." is an abbreviation of the Latin "et alia". Note that "et" is a full word and does not take a period after it.

Below/Above

Use the relative positional specifiers "above" and "below" to refer to position on the same page, and only if you're absolutely sure. What follows "above" or "below" in your word processor's scrolling window does not necessarily occur on the same page. Write for the printed page, not to your word processor or text editor.

LaTeX Tips

Use Tilde (~) for Non-Breaking Spaces

There are certain places where a linebreak where a space occurs can look bad. For example,

As can be seen in Figure
3, our data is wonderful.

looks a whole lot better as

As can be seen in Figure 3,
our data is wonderful.

You can use a tilde (~) in LaTeX to create a non-breaking space, one that LaTeX won't put a linebreak at. Get in the habit of always using a non-breaking space rather than a regular one before \ref or \cite tags. For example,

As can be seen in Figure~\ref{fig:good-data},
our data is wonderful.

Be Careful of Spaces after Periods

Whenever, and I mean whenever, LaTeX sees a period followed by a space, it thinks you've ended a sentence, which means it will put a little extra space after the period. (Remember what your old typing teacher taught you about two spaces after a period? That works for fixed-space fonts and typewriters, but the general principal of using a little extra space after a period still looks good for proportional fonts as well.) But sometimes you didn't mean the period as the end of a sentence, perhaps as part of an abbreviation instead. So,

Dr. Wiseguy

comes out looking like

Dr.  Wiseguy

The way to avoid this is to "escape" the space with a backslash, like this:

Dr.\ Wiseguy

Writing Aids

Strunk and White