98 Copublished by the IEEE CS and the AIP 1521-9615/10/$26.00 © 2010 IEEE Computing in SCienCe & engineering

E d u C A t I o n

Editors: Steven F. Barrett, steveb@uwyo.edu

Rubin Landau, rubin@physics.oregonstate.edu

Technical WriTing Tools for engineers and scienTisTslaTeX versus Business-orienTed Word Processors

By Cameron H.G. Wright

T echnical writing is a necessary skill for essentially every en-gineer and scientist today, and

the tools you choose can greatly influ-ence the ease or difficulty of a particu-lar writing task. For example, if you’re writing journal articles, course mate-rials, technical reports, grant proposals, a book, or even a thesis or disserta-tion, you might find that business-oriented word processors often aren’t well suited to the job.

By “technical writing,” I mean the process of creating a document that:

• is more than a few pages long;• includes nontrivial equations, fig-

ures, and/or tables that you refer to in the text;

• would benefit from logical (often numbered) sections;

• includes a reference list and in-text citations; and

• might include a table of contents, list of figures, list of tables, per-haps an index, and/or one or more appendices.

Although business-oriented word processors certainly can create such documents, most people find that they take much more effort than using a tool designed specifically for techni-cal writing, such as the freely avail-able LaTeX. On the other hand, if the document you need to create is just a

letter or memo, or even a very short report, then the choice of writing tool isn’t as important.

Some organizations strictly dictate that people use a particular software package—such as the ubiquitous Microsoft Office suite—without re-gard for the considerations listed above; others require only that the final file format be standardized (such as Adobe PDF). So, it’s important to know your organization’s rules be-fore you invest much time in inves-tigating different software tools for technical writing.

Here, I’ll compare a typical LaTeX installation to a generic business- oriented word processor—specifically, Microsoft Word (part of the Office suite), but it could just as easily be Corel WordPerfect or OpenOffice Writer (a free software package). This isn’t an exhaustive list of word proces-sors, nor is it intended to be due to space limitations. Some of the newer free online writing tools—such as Google Docs or Zoho Writer—are basically online variations of more traditional business-oriented word processors, and they’re not specifically aimed at technical writing. Finally, it’s not my intention here to disparage business-oriented word processors; they’re sophisticated tools that are very good at their intended purpose: producing business documents.

The Problem with WYSIWYGWhy, when most people are already familiar with programs such as MS Word, should they invest time in learn-ing another writing tool? Traditional business-oriented word processors typically use a what-you-see-is-what-you-get (WYSIWYG) interface: you write directly on a screen repre-sentation that closely mirrors what the printed document will look like. For fairly simple documents, the WYSIWYG approach is relatively intuitive. However, the WYSIWYG paradigm places constraints on docu-ment creation that can be detrimental for technical writing. WYSIWYG can also distract writers into overly “tweak-ing” the document’s look at the ex-pense of concentrating on its content.

LaTeX isn’t WYSIWYG nor was it ever intended to be; it’s basically an easy to learn, high-level programming language for typesetting the most complex documents imaginable. La-TeX macros are easy to use and auto-mate many basic document elements, including

• sectioning, cross-references, and citations;

• equation creation; • figure/table placement; • list generation, including table of

contents; and• global formatting style.

Technical writing poses specific challenges; to meet them, LaTeX goes beyond business-oriented word processors and makes it easier to create complex documents.

CISE-12-5-Edu.indd 98 04/08/10 12:46 AM

September/oCtober 2010 99

Although LaTeX can almost instantly show a detailed preview of what the typeset document will look like, it’s not a WYSIWYG tool; you write the document content in a plain ASCII text file that’s compiled to produce the typeset version.

The LaTeX AlternativeI’ll use an abbreviated file to show how LaTeX produces a finely typeset doc-ument. Figure 1 shows the ASCII text file used as the LaTeX source. This is an excerpt from a file that I pro-vide to my students, many of whom voluntarily transition to LaTeX for technical writing. Figure 2 shows the typeset version of this abbreviated file (scaled down to fit on the page); I’ve added the frame around the page for clarity. The full size of this typeset page is 8.5 × 11 inches, but LaTeX can produce output for any predefined or custom page size.

Document Classes and StylesThe first line in Figure 1 specifies the main class of document—in this case article—and sets the main text font size to 12 points. Four document classes are built-in to LaTeX. In de-creasing order of complexity, they are book, report, article, and letter. Each class has predefined document-appropriate commands. For example, the report and book classes both de-fine the chapter command, which isn’t typically needed in article or let-ter classes (but you can add the com-mand to those classes if you want).

The four base document classes suit most purposes, and you can make minor modifications or additions to each as needed. This is easily accom-plished as shown in Figure 1’s next line, which calls the package (or style file) uwyo_report. As I discuss later, many thousands of prewritten style

files are freely available, or you can write your own. You can also list other packages for various purposes at this point in the ASCII file.

If your document needs are substan-tially different from one of the four base classes, you can use a custom-ized document class. IEEE, for exam-ple, makes available the IEEEtran.cls file, which greatly eases the task of writing for IEEE transac-tions, journals, and magazines. All writers need to do here is to substi-tute IEEEtrans for article in the \documentclass command, and ev-erything will automatically reformat to IEEE requirements. Most other professional societies—including the American Institute of Physics, SPIE—The International Society for Opti-cal Engineering, Optical Society of America, the American Mathemati-cal Society, and the Association for Computing Machinery—have simi-lar document class files for LaTeX, as do most technical conferences. For example, writers for an IEEE Signal Processing Society conference use the article document class and load the spconf style file, which automatically reformats everything to IEEE SPS conference paper requirements. The document contents essentially stay the same; LaTeX simply takes care of the main formatting issues.

Document FormattingAs Figure 1 shows, the primary docu-ment content is contained within the \begin{document} … \end{document} environment. Although the purpose of the \title{} and \author{} commands is obvious, Figure 2 shows how those simple commands take care of placement, spacing, and font selection. If desired, LaTeX also auto-matically inserts the current date and formats it according to the document

class and style. The title, author, and date commands are executed by the \maketitle command. If you switch classes from article to book, the \maketitle command creates a sep-arate title page. The special format-ting requirements of an abstract are applied to the \begin{abstract} … \end{abstract} environment, again according to the selected document class and style. The \section{} command designates the text’s vari-ous sections as well as the section’s numbering, placement, spacing, and font selection. Commands such as \subsection{} and \subsubsection{} further organize the document. As Figure 1 shows, list formatting is also easily accomplished, including item-ized lists with bullets, enumerated lists (numbers and letters), and defini-tion lists. Depending on the document class and style, other special environ-ments are also available, including theorem, lemma, and quotation.

LaTeX makes formatting citations particularly easy. The \cite{} com-mand’s arguments in Figure 1 are key names the writer has given to entries in a simple ASCII database of bib-liographic entries—in this case, the sample_bib.bib file. Various free utilities, such as the excellent JabRef program (http://jabref.sourceforge.net/), offer an easy interface for maintain-ing such bib files, and can even down-load directly from online sources such as the IEEE Xplore Digital Li-brary, ACM Portal, CiteSeer, JStor, Web of Science, and Medline. The \bibliographystyle{} command dictates the reference formatting; in this case, I’ve specified the freely avail-able ieeetr.bst file, which formats the bibliography according to IEEE requirements. The \bibliography{} command provides a link to the Bib-TeX helper program, which accesses

CISE-12-5-Edu.indd 99 04/08/10 12:46 AM

E d u C A t I o n

100 Computing in SCienCe & engineering

the specif ied bib f i le database and creates the reference list (see Figure 2).

Creating other parts of a technical document, such as a table of contents, list of figures, list of tables, an index,

and so on, are also easy with LaTeX: you simply include commands—such as \tableofcontents, \listoffigures,

Figure 1. the ASCII text file used as the LateX source. this file contains the formatting commands and the source text for a short example document. LateX will quickly compile and typeset this file to produce the result seen in Figure 2.

CISE-12-5-Edu.indd 100 04/08/10 12:46 AM

September/oCtober 2010 101

or \listoftables—in the appro-priate place in the ASCII file to cre-ate the desired list, perfectly typeset.

You can also easily create custom lists, such as a list of examples and program listings.

Working with ElementsThe power of using LaTeX for tech-nical writing becomes even more

Figure 2. the typeset version of the ASCII file shown in Figure 1 (scaled down to fit the page). note how the simple commands in the ASCII file of Figure 1 result in ideally spaced and sized document elements such as title, author names, date, section headings, references, and so on. the formatting power of LateX becomes even more useful as the document becomes larger and more complex.

CISE-12-5-Edu.indd 101 04/08/10 12:46 AM

E d u C A t I o n

102 Computing in SCienCe & engineering

obvious when you need to include equations, figures, tables, program listings, and so forth. In a program such as MS Word, equations can be created in a WYSIWYG manner us-ing the built-in equation editor, which provides barely adequate formatting and inevitably interrupts your train of thought. It often produces oddly spaced equations, symbols, and char-acters, and equation numbering and cross-referencing is neither easy nor intuitive.

In contrast, with just a bit of ex-perience using LaTeX, you can al-most effortlessly write, number, and cross-reference equations. As a simple example, suppose you want to include an inline equation for the Euclidean distance metric in 2D space, which is

r x y= +2 2 .

Using the MS Word equa-tion editor, you have to stop typ-ing and use the mouse to select “Insert→Object→Microsoft Equation,” which opens a separate dialog box. You then type “r =” and use the mouse to find and click on the square root symbol, and then type “x, Ctrl-h 2, space, +, space, y, Ctrl-h 2” (assum-ing you know the keyboard shortcut Ctrl-h for superscript) and close the dialog box. You then find the equation placed in the text, with little regard for appropriate spacing and scaling. A bit of tweaking is typically needed to get it to look halfway decent.

Using LaTeX, you don’t need to stop typing but instead simply type $r=\sqrt{x∧2 + y∧2}$ and a beauti-fully formatted and scaled inline equation becomes part of the typeset document. Unlike in MS Word, the need to include an equation doesn’t interrupt your train of thought in the

least. (As this example shows, in La-TeX, the dollar sign has special mean-ing; if you need an actual dollar sign, you just type “\$” instead.)

If you want your equation to appear as a display equation rather than an inline equation, you just replace the $ … $ with \[ … \] and the formatting automatically changes. If you need to number the equation, you replace \[ … \] with \begin{equation} … \end{equation}. Also, if you add \label{MyEqNum} to the equation def-inition, you can refer to the equation using the command \ref{MyEqNum} anywhere in the document. Anyone who has tried to accomplish similar tasks in MS Word is probably starting to appreciate LaTeX about now.

Further, LaTex lets you define frequently used expressions as mac-ros. To make our earlier equation a macro, for example, you place \def\myEq{$r=\sqrt{x^2 + y^2}$} somewhere before the \begin{document} command, and wherever you type “\myEq\” in the text, the inline equation will appear. You can also use macros for text, such as \def\ml{\textsc{Matlab}} to get the properly formatted word “Matlab” to appear wherever you type “\ml\” in the text. Macros can also accept optional and mandatory arguments as desired; this is part of the power of us-ing a typesetting language.

Our simple example equation doesn’t require much in the way of complicated typesetting, but in a side-by-side comparison, the equa-tion formatted by LaTeX still looks better. The differences are subtle, but the font scaling, spacing around sym-bols, and overall layout is superior. The differences become much more pronounced with more complicated equations and expressions. There’s a reason that many people around the

world consider LaTeX the gold stan-dard for typesetting equations.

So, what about figures and tables? You can easily define them in LaTeX as hav-ing either fixed or floating placement. Fixed means the object will appear at the same place as the appropriate com-mand (such as \includegraphics{} or \begin{tabular} … \end{tabular}). Floating means the object can “float” to the top or bottom of the page, to the following page, or “here” as needed to properly balance text and objects. Floating placement uses the \begin{figure} … \end{figure} or \begin{table} … \end{table} environments, and allows automatic caption numbering and formatting, easy cross-referencing, and so forth. Typically, figures are included us-ing standard formats such as EPS or PNG, but users can even draw intri-cate figures using the native LaTeX typesetting language. Further, there are freely available packages with symbol libraries for chemistry, phys-ics, electrical engineering, and many other fields.

Although LaTeX was originally intended for technical writing, the power and beauty of its typesetting capabilities have inspired developers to create document classes and pack-ages for diverse writing applications ranging from creating perfectly type-set musical scores to producing spe-cially formatted scripts for theater and film.

Choosing an EditorBecause a LaTeX source file is just a simple ASCII file, the question of which editor to use naturally arises. The simple answer is that you can use any editor you want that can produce an ASCII file—whether it be a pro-gram such as Notepad, Vi, or Emacs, or ASCII editors tailored to LaTeX users.

CISE-12-5-Edu.indd 102 04/08/10 12:46 AM

September/oCtober 2010 103

The latter have a considerable ad-vantage in that you can use them as an integrated front end to the en-tire LaTeX installation, including features such as one-click compile/ preview, automatic insertion of LaTeX commands and environments, spell checking, syntax checking, help files, and so forth (see http://en.wikipedia. org/wiki/Comparison_of_TeX_editors). The disadvantage is that most of the specialized LaTeX editors are avail-able only for Windows. Popular Windows-based editors specialized for LaTeX include the freely avail-able TeXnicCenter (www.texniccenter. org) or the inexpensive shareware program WinEdt (www.winedt.com), which is highly regarded and consid-ered by many to be the top LaTeX editor.

LaTeX FontsA common misconception about La-TeX is that it limits your choice of fonts. Many LaTeX documents are printed using the Computer Modern fonts, which were created along with LaTeX to have all the needed math fonts and symbols—something many other fonts lack even today.

Computer Modern is a distinctive font set; some people love them and others don’t. In any case, they’ve be-come so closely associated with La-TeX that some people assume that LaTeX uses only those fonts. In fact, most LaTeX installations since 1989 can use any available Postscript or TrueType font, and hundreds of font definition files are freely available.

Another misconception concerns a LaTeX document’s output file. Although any early LaTeX instal-lation could produce a device-inde-pendent (DVI) file, modern LaTeX installations can directly produce other output file formats as well,

including Postscript, PDF, HTML, and XML.

I’ve been a happy user of LaTeX since I was a grad student in the

early 1990s. In that time, I’ve used LaTeX to produce class reports, a dissertation, journal and confer-ence papers, presentations, full-size posters, small business cards, letters (with and without letterhead), mem-os, quizzes, exams, and full-length books. I revert to something such as MS Word or PowerPoint only when forced to do so for what are often ar-bitrary compatibility reasons. Once the power of LaTeX is clear, it’s dif-ficult to go back to a WYSIWYG writing tool. Over time, you build up quite a library of style files, skeleton files, and a bibliography database, so that it gets increasingly easier to accomplish your writing tasks with LaTeX. That’s why there are many thousands of LaTeX users around the world.

Based on TeX, the typesetting en-gine created by Donald Knuth, LaTeX is in the public domain and a world-wide community has continuously updated, expanded, and supported it since the 1980s. It’s available for nearly every known platform and op-erating system, including Windows, Mac, Unix, Linux, and AmigaOS. La-TeX is both mature and cutting edge, and any significant new document creation trends quickly find their way into updates. There’s a massive col-lection of free style files, programs, documentation, tutorials, and other helpful items available through TUG, the TeX Users Group (see www.tug.org). The main files repository is the comprehensive TeX archive network (CTAN) and has mirror sites all over the world.

It’s been said that more has been written both in print and online about LaTeX than any other comput-er-based writing tool in the world, and I suspect that’s true. There are plenty of articles that describe it in more detail,1–4 or you can simply perform a quick Google search on “LaTeX” to find thousands of help-ful websites. For quick overviews, I recommend www.latex-project.org or http://en.wikipedia.org/wiki/LaTeX. If you’re willing to venture outside your WYSIWYG comfort zone and try out LaTeX, you might just find the burden of writing technical docu-ments considerably eased.

References 1. L. Lamport, LaTex: A Document Prepara-

tion System, 2nd ed., Addison-Wesley,

1994.

2. F. Mittelbach and M. Goosens, The

LaTex Companion, 2nd ed., Addison-

Wesley, 2004.

3. G. Grätzer, More Math Into LaTeX, 4th

ed., Springer, 2007.

4. E. Wessler, “An Argument for Learning

Latex: the Benefits of typesetting and

Beyond,” TUGboat: The Communications

of the TeX Users Group, vol. 31, no. 1,

2010, pp. 6–8.

Cameron H.G. Wright is an associate pro-

fessor in the Electrical and Computer En-

gineering department at the university of

Wyoming. His research interests include

signal and image processing, real-time em-

bedded computer systems, biomedical in-

strumentation, and engineering education.

Wright has a Phd in electrical engineering

from the university of texas at Austin. Con-

tact him at c.h.g.wright@ieee.org.

Selected articles and columns from IEEE Computer Society publica-

tions are also available for free at http://ComputingNow.computer.org.

CISE-12-5-Edu.indd 103 04/08/10 12:46 AM