Lecture Notes on Technical Writing (Part 2 of 2)
⇐
Previous Lecture Notes
 ⇑ Up
Next Lecture Notes ⇒

Summary
MENU

1. Types of Technical Documents

There are a variety of documents that scientists and engineers need to read and/or write.

The development of a system or product requires system documentation that commonly consists of the following documents.

2. Technical Specifications

An English dictionary defines the word "specification" as an act of describing or identifying something precisely or of stating a precise requirement.
A document produced by specification is specifications (usually in the plural form) that describe in detail the design and materials used to make someting.

It is common to write technical specifications in a tabular form.

Example 2.1:
The following is an excerpt of specifications of ASUS motherboard Z10PE-D16 WS.

CPU Build in Intel® Socket 2011-3: Square type (80x80mm) Processors
Intel® Socket 2011-3 for Intel® Xeon® processor E5-2600 v3 product family
Intel® Socket 2011-3 for Intel® Xeon® processor E5-2600 v4 product family
Chipset Intel® C612 PCH
Memory 16 x DIMM, Max. 1024GB, DDR4 1866*/2400/2133/1600 MHz RDIMM, LR-DIMM Memory *1
Quad Channel Memory Architecture
Graphic ASpeed AST2400 32MB
VGA port*2
- Supports VGA with max. resolution 1920 x 1200 @ 60 Hz
Multi-GPU Support Supports NVIDIA® 3-Way SLI™ Technology
Supports AMD Quad-GPU CrossFireX™ Technology
Expansion Slots 4 x PCIe 3.0/2.0 x16 (x16 mode) *3
2 x PCIe 3.0/2.0 x16 (x8 mode) *3
LAN Intel® I210-AT, 2 x Gigabit LAN Controller(s)
1 x Management LAN
Back I/O Ports 1 x PS/2 keyboard/mouse combo port(s)
2 x LAN (RJ45) port(s)
4 x USB 3.0 (blue)
4 x USB 2.0 *6
1 x Optical S/PDIF out
1 x USB BIOS Flashback Button(s)
1 x Q-Code Logger button
1 x 8-channel Audio I/O
1 x Management LAN
BIOS 128 Mb Flash ROM, UEFI BIOS, PnP, WfM2.0, SMBIOS 2.6.1, ACPI 3.0, ASUS EZ Flash Utility, ASUS CrashFree Technology
Operating System Windows® Server 2012 R2
Windows® Server 2012
Windows® Server 2008 Enterprise SP2 64-bit
Windows® 8.1 64-bit
Windows® 8 64-bit
Windows® 7 32/64-bit
Form Factor EEB Form Factor
12 inch x 13 inch ( 30.5 cm x 33.02 cm )
Weight Color Box (1-in-1)
Net Weight : 1.49 kg
Gross Wright : 3.2 kg
Bulk Pack(5-in-1)
Net Weight : 7.45 kg
Gross Weight : 9.9 kg
Environment Operation temperature: 10℃ ~ 35℃
Non operation temperature: -40℃ ~ 70℃
Non operation humidity: 20% ~ 90% (Non condensing)

Remark 2.1:

Example 2.2:
View technical specifications of Samsung 32" 970 Series UHD Professional LED Monitor U32D970Q#key-specs

Example 2.3:
View technical specifications of Daikin Split System Air Conditioners "Ururu Sarara 7" Series

Specifications of a software product describes various aspects of the software product from different viewpoints
such as functionality, interfaces, performance, security and reliability.
Especially, the functionality is indispensable and most important among them.
Software specifications are also classified, depending on which phase the development of software is in,
such as requirements, design, implementation and testing.

Software specifications also clarify hardware and software environments necessary for installing and/or running software such as the following.

Software specifications often employ visual representations
such as control flow diagrams, data flow diagrams, trees depicting hierarchical structures, data model for a database schema, and behavior diagrams for describing external interfaces.
Many of the diarams for software specifications are drawn in UML (Unified Modeling Language).
There are useful tools for diagram drawing that are syntax-driven so that the syntax of a diagram is automatically enforced.

3. Manuals

What Are Manuals?

Documentation of actions and/or procedures to standardize tasks, operations and decision criteria

Types of Manuals

Example 3.1:
View a user's guide " Getting Started" of Apache HTTP Server v.2.4

Example 3.2:
View " Introduction to Android" for Android Developers

Example 3.3:
View a Developer's Guide for Building a Chrome Extension − Getting Started

4. Figures and Tables

It is wise to present information by using its visual representations such as diagrams, graphs, charts, and tables.
However, visual representations sometimes mislead the readers possibly due to their ambiguity.
Thus, in technical writing, you must carefully design how to present information visually.

Figures

Every figure should have a numbered label and a caption beneath the figure as shown below.
There must be at least one reference to each figure in text.
A figure should be placed on the same page where the first reference to the figure occurs.
Ideally, the figure is placed near the first reference to it.
  1. Diagrams

    As an example of a figure containing a diagram, see Figure 1 below.

    Figure 1:
    An encoding scheme for representing a path of a mobile robot in a genetic algorithm.

  2. Graphs

    As examples of a figure containing a graph, see Figures 2 and 3 below.

    Figure 2:
    Lopt vs mutation rate and win rate.

    When there are multiple data plots within a graph, the data plots must be explained and distinguished in a legend.

    Figure 3:
    Lopt vs population size.

  3. Charts

    Figure 4:
    Ethnic population in Hawaii.

    (data source from the U.S. Census Bureau in 2010)
    		    

    Figure 5:
    Hawaii Demographics.

    (data source from the U.S. Census Bureau in 2010)

    Figure 4 is an example such that a visual representation of information is possibly misleading.
    As Hawaii is often called as a "mixed plate", many residents of Hawaii claim to have multiple ethnicities.
    Some of them have several or more ethnicities.
    Thus, simply grouping people by single ethnicity in Hawaii may not accurately represent reality.

  4. Pictures

    etc.

Tables

Every table should have a numbered label and a caption just above the table (see Tables 1 and 2 as shown below).
Like figures, there must be at least one reference to each table in text.
A table should be placed on the same page where the first reference to the table occurs.
Ideally, the table is placed near the first reference to it.

Table 1:
Adaptivility of the genetic algorithm.
No. obstacles ave. N1 std of N1 ave. N2 std of N2
10
15
20
25
30 		3.7
57.6
16.1
356.4
4.4 		2.61
43.36
16.50
287.84
5.43 		18.1
88.1
23.8
261.6
18.4 		12.34
61.94
30.54
234.56
19.46
overall 87.6 188.29 82.0 144.31

The first row of a table usually contains a title of each column of the table.
Horizontal lines must be drawn just above the first row, beneath the first row, and beneath the last row.
Whether other rows are separated by horizontal lines or not depends on the content of a table.
It is common to separate columns by vertical lines.
Vertical lines at the left and right ends of a table are sometimes omitted (see Table 2).

Table 2:
The number of visitors by island in Hawaii.

(source: Hawaii Visitor Bureau in 2015)
Island | Domestic      | International
Oahu | 21,038,028      | 15,382,475
Maui | 17,948,613      | 3,298,484
Big Island | 9,779,912      | 1,683,928
Kauai | 8,183,081      | 771, 560

5. Typesetting and Formatting
In science & engineering, LaTeX is the de facto typesetter.
It provides us with a rich set of macros for typesetting and formatting technical documents.
It is especially best when you need to write mathematical formulas.

Set a LaTeX environment up on your computer.
Once LaTeX is ready to use on your computer, try to compile the example LaTeX source file that generates a PDF.

There are also websites providing online LaTeX environments with some guidance for beginners.

Regarding LaTeX, refer to Wikibooks on LaTeX/Formatting and LaTeX Reference Manual.

Page Numbering

A page number must be shown on each page whenever a document is of two or more pages long.
LaTeX provides us with typical styles of page numbering.
The most common style is to print a page number in Arabic numeral at the center of a bottom margin.
Pages preceding the first page of the main text (e.g., preface and a table of contents) are commonly numbered in Roman numeral (e.g., iii, iv and xii for 3, 4 and 12).

Headings

A heading is a title at the beginning of a chapter or a section or a paragraph.
It is commonly a word or a short phrase that represents the main theme of a chapter or a section or a paragraph.
Appropriately chosen headings are a very effective way to enable readers to grapse the essence of a technical document quickly.

Table 5.1: Headings ("..." denotes a heading)
LaTeX HTML (numbering is not automatic)
Chapter \chapter{ ... }
Section \section{ ... } <h1> ... </h1>
Subsection \subsection{ ... } <h2> ... </h2>
Subsubsection \subsubsection{ ... } <h3> ... </h3>
Paragraph \paragraph{ ... }

Example 5.1:
Take a look at the folowing paragraphs without headings.
Paragraphs without headings
Then, read the following with headings.
You will find the latter is easier to comprehend than the former.
Paragraphs with headings

Running Heads

A running head is a short title of each page shown at the top margin.
A document may or may not include running heads.
In general, running heads are shown in a document when the document is formal or long.

Bullet Lists

In technical writing, a bullet list (or sometimes called an itemized list) is often better than elaborating in plain text.
Especially, it is best to present a classification, an enumeration (without a particular ordering).

Example 5.2:
Read the following paragraph on languages for specifying Abstract Data Types (ADTs).
There are two types of languages for specifying Abstract Data Types (ADTs). The first type is a class of formal languages. They employ formal techniques such as an axiomatic method, an algebraic method, a functional method, denotational semantics, etc. The second type is a class of natural languages such as English.
This paragraph may be rewritten by using bullet lists as follows.

Specification Languages for ADT
  • Formal Languages
    • Axiomatic Method
    • Algebraic Method
    • Functional Method
    • Denotational Semantics
      etc.
  • Natural Languages
The latter is ovbiously clear and concise.
Furthermore, the latter makes it much easier to comprehend than the former.

Numbered Lists

A numbered list is often used in a similar way as a bullet list,
except that there is a particular meaning in the ordering of items in a numbered list,
e.g., precedence relationships among items and priorities of items.

Example 5.3:
Read the following paragraph of a historical summary on switching devices for digital circuits.
A variety of electronic elements were developed for implementing logical operators. First, relays were used and then replaced by vacuum tubes such as triodes, tetrodes and pentodes. Then, semiconductor devices came out. Diodes were developed first. Then, bipolar transistors were introduced. To reduce a power consumption, FET (Field-Effect Transistor) were developed. It evolved into MOS FET (Metal–Oxide–Semiconductor FET) and then CMOS FET (Complementary MOS FET). In recent years, optical transistors have been developed. They will lead us to photonic computing.
This paragraph may be rewritten by using numbered lists as follows.

Switching Devices for Implementing Logical Operators in Digital Circuits (in the chronological order)
  1. Relay Switch
  2. Vacuum Tube (Triode, Tetrode, Pentode, etc.)
  3. Semiconductor Device
    1. Diode
    2. Bipolar Transistor
    3. FET (Field-Effect Transistor) with a Much Lower Power Consumption than a Bipolar Transistor
      1. MOS FET (Metal–Oxide–Semiconductor FET)
      2. CMOS FET (Complementary MOS FET)
  4. Optical Transistor (under development) → Photonic Computing
    etc.

The latter is ovbiously clear and concise.
The numbered lists in this example imply a chronological ordering of switching devices.

Footnotes

A footnote is an additional description (typically short, e.g., a sentence or two) printed in the bottom margin of a page about a word or a sentence in the main text on the same page.
The word or sentence is marked by a special symbol such as an asterisk "*", a dagger "†", a double dagger "‡", a section sign "§" and a plus sign "+".
Then, the corresponding footnote begins with the same symbol so that the reader can easily identify which footnote is tied with the marked word or sentence.

It is recommended to refrain from using footnotes
except that a paper commonly includes a footnote regarding grants for research on the first page.
Books often include footnotes though, footnotes are not necessary in most of cases.
Other than books, footnotes should be avoided unless there is an obvious benefit of using a footnote.

Acknowledgments

An acknowledgment is a sentence of thanking someone or an organization that assisted an author and made a contribution to a paper
(e.g., you received some advice on a paper and you received a grant).
Acknowledgments are usually placed between the last section and references.
In case of books, acknowledgments precede a table of contents.

Note that "acknowledgment" is spelled without e between g and m in U.S.A. while it is commonly spelled as "acknowledgement" with e in U.K.

References (or Bibliography)

A list of citations to references is placed at the end of a document (but usually preceding appendices and indices).
The list is often called a bibliography in case of books, theses and dissertations.
Each publication has its own format of citations.
Hence, you need to make it sure that your paper complies the format.

In STEP fields, most of citation formats are commonly based on the citation format of Chicago Manual Style (CMS) with minor variations.

Appendix

An appendix is an additional section excluded from the main sequece of chapters or sections of a document
due to some of the following reasons.
  1. A document is better organized by moving an appendix out from the main sequence of chapters or sections.
  2. Information of an appendix are too detailed (e.g., roa data of an experiment and source code of a program) to include in an ordinary section.
  3. Information of an appendix is prior knowledge that authors presume their anticipated readers to have though, the authors add the appendices to the document as just references for the readers.
It is not common that papers in journals and conference proceedings have appendices though, some books have appendices.

Appendices are placed at the end of a document (usually following references, but preceding indices).
In case of books, appendices usually follows the last chapter and precedes references and indices.

Subject Index (or Glossary)

A subject index is a lexicographically sorted list of technical terms with pointers to pages including each term.
A glossary plays a similar role as a subject index though, a glossary is a list of terms with their definitions and/or explanations (not necessarily including page numbers).

A book must contain a subject index while it is unusual that a paper contains a subject index.

Table 5.1: A Typical Organization for Each Type of a Technical Paper
 
Books
Cover Page
Copyright Page
Table of Contents
Preface
Acknowledgments
Chapter 1
  .
  .
  .
Chapter N [Last Chapter]
Appendices [Option]
Bibliography
Index
     
Journal Papers
Conference Papers
Title
Authors
Affiliations
Abstract
Keywords [Option]
1. Introduction
2. Preliminaries
  .
  .
  .
N. Conclusion [Last Section]
Acknowledgments [Option]
References
     
 
Theses or Dissertations
Cover Page
Abstract
Table of Contents
List of Figures
List of Tables
Acknowledgments
Chapter 1 Introduction
  .
  .
  .
Chapter N [Last Chapter]
Bibliography
Appendices [Option]

Editorial Styles

Each field has its own style of technical writing.
Relevant to computer science, there are two major international organizations:
IEEE (the Institute of Electrical and Electronics Engineers) and ACM (the Association for Computing Machinery).
Each of the organizations expects CS professionals to follow its style of technical writing, although they are similar with many minor differences.

Example 5.2:
Refer to a LaTeX sample template (PDF) for a technical report with the IEEE style class file in the draft mode (double space).

Example Documents Typeset by LaTeX

6. Exercises
  1. Write technical specifications of the following LCD display
    : Iiyama 27" Gaming LCD Display: ProLite GB2773HS-2.

  2. Write technical specifications of the following air conditioners.

  3. Write technical specifications of the following elevator: 東芝エレベータ 駅舎用.

  4. Write technical specifications of your own smartphone with respect to the following aspects
    .

  5. Write instructions for each of the following operations on the Web Browser that you commonly use.

  6. Write instructions on the initial settings of the following App on smartphone.
    KDDI 名刺バンクのスマホ初期設定説明書

  7. Read the following section of Lecture Notes on graph theory.
    Then, give an appropriate heading for the section.

    A traversal is to visit all vertices in a graph. It is one of the most primitive tasks to solve graph problems. For example, how can you know the number of vertices or edges in a given graph?

    There are two systematic ways to perform a traversal.

    • Depth-First Search (DFS)
    • Breadth-First Search (BFS)

    Example 1.1: DFS on an Undirected Graph 

            v2             v3            v5
         o-------------o-------------o
        /|             |
       / |             |
      /  |             |     o v8
  v1 o   |             |    /
      \  |             |   /
       \ |             |  /
        \|             | /
         o-------------o-------------o
        v4             v6            v7
    Suppose that v1 is the start vertex of DFS. Here is a trace of an execution of the RecursiveDFS(G,v1), where the for loop chooses adjacent vertices w of v in the increasing order of their indices. 
    start
  |
  visit v1               /|                      /|
  |                     / visit v2              / visit v3                          /|
  |                    /  |                    /  |                    /|          / visit v6
  |                   /   Recursive DFS(G,v3) -   Recursive DFS(G,v5) - visit v5  /  |                    /|
  Recursive DFS(G,v2) -   |                    \  |                    \|        /   Recursive DFS(G,v4) - visit v4
  |                   \   |                     \ Recursive DFS(G,v6) -----------    |                    \|        /|
  |                    \  |                      \|                              \   Recursive DFS(G,v7) ----------- visit v7
  |                     \ [v4 already marked]                                     \  |                    /|        \|
  |                      \|                                                        \ Recursive DFS(G,v8) - visit v8
  |                                                                                 \|                    \|
  [v4 already marked]
  |
end