Technical Writing Tools for Engineers and Scientists

  • View
    220

  • Download
    7

Embed Size (px)

Text of Technical Writing Tools for Engineers and Scientists

  • 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 youre 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 arent 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 isnt as important. Some organizations strictly dictate

    that people use a particular software packagesuch as the ubiquitous Microsoft Office suitewithout re-gard for the considerations listed above; others require only that the final file format be standardized (such as Adobe PDF). So, its important to know your organizations rules be-fore you invest much time in inves-tigating different software tools for technical writing.Here, Ill compare a typical LaTeX

    installation to a generic business- oriented word processorspecifically, Microsoft Word (part of the Office suite), but it could just as easily be Corel WordPerfect or OpenOffice Writer (a free software package). This isnt an exhaustive list of word proces-sors, nor is it intended to be due to space limitations. Some of the newer free online writing toolssuch as Google Docs or Zoho Writerare basically online variations of more traditional business-oriented word processors, and theyre not specifically aimed at technical writing. Finally, its not my intention here to disparage business-oriented word processors; theyre 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 documents look at the ex-pense of concentrating on its content.LaTeX isnt WYSIWYG nor was

    it ever intended to be; its 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, its not a WYSIWYG tool; you write the document content in a plain ASCII text file thats compiled to produce the typeset version.

    The LaTeX AlternativeIll 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); Ive 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 documentin this case articleand 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 isnt 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 1s 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 societiesincluding the American Institute of Physics, SPIEThe International Society for Opti-cal Engineering, Optical Society of America, the American Mathemati-cal Society, and the Association for Computing Machineryhave 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 texts vari-ous sections as well as the sections 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-mands arguments in Figure 1 are key names the writer has given to entries in a simple ASCII database of bib-liographic entriesin 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, Ive 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 commandssuch 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.