Guidelines for Engineering a
High Quality Technical Document
Osman Balci Professor
Department of Computer Science
3160B Torgersen Hall, MC 0106
Virginia Polytechnic Institute and State University
Blacksburg, Virginia 24061, U.S.A.
Version: October 31, 2011
[email protected] — http://manta.cs.vt.edu/balci
Technical Document
We use the term technical document to refer to any type of technical document such as Book
Edited Book
In an Edited Book
Journal
In a Conference Proceedings
Technical Report
Thesis
Dissertation
Research Proposal
Special Publication
Edited Special Publication
In an Edited Special Publication
The Guidelines presented herein apply to all of these types of documents.
Apply Software Engineering Principles
View technical document development as a software engineering activity.
A technical document is actually engineered as a product, and as such, it is subjected to quality assessment like any other product.
Many similarities exist between creation of a technical document and engineering of a software product.
You can create a high quality technical document by properly applying the software engineering principles.
Apply Software Engineering Principles
Many software engineering principles can be applied for engineering a technical document including:
Life Cycle
Identify the Requirements for the Document
Design (Structure) the Document
Implement (i.e., write) the Document
Maintain the Document (if applicable)
Modularization / Decomposition
Cohesion and Coupling
Progressive Elaboration / Iterative Refinement
Incremental Development
Top-Down or Bottom-Up Development
Modularization / Decomposition
Document
Chapters
Sections
Subsections
Paragraphs
Sentences
Words
Modularization / Decomposition
Document
Chapter Chapter Chapter … Chapter
1 2 3 N
Section Section Section … Section
1 2 3 S
Section Section Section … Section
3.1 3.2 3.3 3.J
Section Section Section … Section
3.2.1 3.2.2 3.2.3 3.2.K
Section Section Section … Section
3.2.3.1 3.2.3.2 3.2.3.3 3.2.3.L
Chapter Level
Level 1
Level 2
Level 3
Level 4
Possible Document Modules
Title Page (no page number)
Abstract † (page number ii)
Table of Contents † (page number iii)
List of Figures †, List of Tables †, List of Acronyms †
Introduction (page number 1)
Background
Overview
Fundamental Concepts
Purpose and Motivation
Motivation and Scope
Definitions and Terminology
Terminology
Notation and Definitions
Problem Definition
Relevant Literature
Literature Review
:
† Unnumbered
Note that the list
suggests
alternative names
for some sections
one of which may
be selected.
Possible Document Modules
:
<body of the technical document>
:
Conclusions
Conclusions and Future Directions
Conclusions and Future Work
Conclusions and Open Problems
Concluding Discussions
Concluding Remarks (contains topics that are not covered in the
body of the document.)
Discussion
Future Directions
Future Research
Future Research Topics
:
:
Note that the list
suggests
alternative names
for some sections
one of which may
be selected.
Possible Document Modules
:
:
New Directions
Research Directions
Summary
Summary and Conclusions
Summary and Research Directions
Glossary †
Glossary of Selected Terms †
Appendix †
Acknowledgments †
References †
Bibliography †
Annotated Bibliography † † Unnumbered
Note that the list
suggests
alternative names
for some sections
one of which may
be selected.
How to Write an Abstract
An Abstract is very different from Summary.
It is typically written as one large paragraph.
Usually a size limit is specified as maximum number of words, e.g., 250.
An Abstract has its own unique structure, and it should be engineered with respect to that structure.
How to Write an Abstract
1. What is the problem?
2. Why is the problem important to solve?
3. What did you do to solve the problem?
4. What is your solution? Give a brief description of your solution.
5. What do you conclude and recommend about your solution?
Structure your Abstract by way of responding to the following questions.
The questions need to be interpreted and mapped depending on the document’s topic.
How to Write an Abstract: An Example
Recent paradigm shift from considering software as a product to treating software as a service has produced
capabilities for engineering complex network-centric military systems. As the industry works on building a
cyberinfrastructure and the Department of Defense moves toward network-centric operations and warfare,
military systems are becoming network-centric system of systems and family of systems consisting of software,
hardware, and humans. Assessment of the architecture of such a network-centric military system is a very complex
process, involves the measurement and evaluation of hundreds of qualitative and quantitative elements, mandates
subject matter expert evaluation, and requires the integration of disparate evaluations obtained by testing, direct
measurement, analysis, and examination. Planning and managing such measurements and evaluations require a
unifying methodology and should not be performed in an ad hoc manner.
This paper presents such a methodology named Military System Architecture Assessment Methodology (MSAAM).
MSAAM advocates mission-oriented risk-driven architecture assessment based on four assessment perspectives:
product, process, people, and project. It consists of seven stages: (i) specification of missions, (ii) specification of use
cases for accomplishing the missions, (iii) employment of subject matter experts, (iv) identification of indicators for
system architecture assessment, (v) relative criticality weighting, (vi) score assignments for the leaf indicators, and
(vii) score aggregation, score analysis, and assessment report generation.
MSAAM enables the decomposition of architecture assessment into small pieces corresponding to leaf indicators
and provides a structured framework for overcoming the complexity of architecture assessment.
1. What is the problem?
2. Why is the problem important to solve?
3. What did you do to solve the problem?
4. What is your solution? Give a brief description of your solution.
5. What do you conclude and recommend about your solution?
How to Write an Introduction for a Journal or Conference Paper
A journal or conference proceedings paper typically starts with the Introduction section.
In this section, background information is provided and some definitions are given to prepare the reader for the subsequent sections.
A journal or conference proceedings paper does not include a Table of Contents.
Therefore, the last paragraph of the Introduction section should provide an outline of the paper.
Example last paragraph:
This paper is organized as follows. Section 2 describes earlier work leading to the
development of the network-centric MSAAM. Network-centric military system
characteristics are described in Section 3. These characteristics illustrate the complexity
of the problem domain and the assessment task. Four perspectives under which
architecture assessment is advocated are presented in Section 4. The network-centric
MSAAM is presented in Section 5. Concluding remarks are given in Section 6.
How to Write a Paragraph
Engineer your paragraph with the highest possible Cohesion and the lowest possible Coupling.
To achieve High Cohesion, include sentences that highly relate to paragraph’s topic. The more the sentences relate to the topic, the higher the paragraph Cohesion will be.
To achieve Low Coupling, include cross references that are automatically changed by the document creation software.
Shorter paragraphs are generally easier to comprehend. However, sometimes it may be necessary to have a long paragraph in order to provide the highest possible cohesion.
A paragraph's length should be judged with respect to its cohesion.
How to Write a Paragraph
Use the Funnel Technique
1st Sentence
2nd Sentence
3rd Sentence
4th Sentence
5th Sentence
Highest level (least detailed)
coverage of the topic.
Lowest level (most detailed)
coverage of the topic.
The more sentences you add, the more detail you provide about paragraph's topic.
The sentences must be all about the same topic!
Writing Style
Use Present Tense unless there is a compelling reason to use Past Tense.
DO: We present a methodology in this paper.
DO NOT: We presented a methodology in this paper.
Use Active Voice as opposed to Passive Voice. Research enunciates that Active Voice is much more comprehensible than the Passive Voice (or third person voice)
DO: We present a methodology in this paper.
DO NOT: A methodology is presented in this paper.
Construct concise sentences. Do NOT be Verbose! Read your sentence and ask yourself: Can I shorten this sentence without sacrificing clarity?
e.g., Verbose: There are three approaches…
Concise: Three approaches exist…
Writing Style
Never use “I” in your technical writing even if you are the single author of the document.
DO: We present a methodology in this paper.
DO NOT: I present a methodology in this paper.
Define each Acronym at its first use!
An acronym must have only one definition.
DO NOT: create the acronym M&S to stand for Modeling
& Simulation and also for Models & Simulations.
Every sentence you write, every word you use, every claim you make must be defendable.
DO NOT: make claims that cannot be substantiated by
referring to a publication.
e.g., “Windows is the best computing platform.”
How to List References
List references as unnumbered, in alphabetical order with respect to the last name of the first author.
This approach provides the best maintainability and readability since they are cited by using author names.
Balci, O. (2001), “A Methodology for Certification of Modeling and Simulation Applications,” ACM Transactions
on Modeling and Computer Simulation 11, 4 (Oct.), 352-377.
Balci, O. (2004), “Quality Assessment, Verification, and Validation of Modeling and Simulation Applications,” In
Proceedings of the 2004 Winter Simulation Conference (Washington, DC, Dec. 5-8). IEEE, Piscataway, NJ,
pp. 122-129.
Clements, P., R. Kazman, and M. Klein (2002), Evaluating Software Architectures: Methods and Case Studies,
Addison-Wesley, Boston, MA.
DoDAF (2004a), “DoD Architecture Framework Version 1.0 Volume I: Definitions and Guidelines,” Architecture
Framework Working Group, Department of Defense, Washington, D.C., Feb. 9,
http://www.dod.mil/nii/doc/docArchive.html#NII
DoDAF (2004b), “DoD Architecture Framework Version 1.0 Volume II: Product Descriptions,” Architecture
Framework Working Group, Department of Defense, Washington, D.C., Feb. 9,
http://www.dod.mil/nii/doc/docArchive.html#NII
DoDAF (2004c), “DoD Architecture Framework Version 1.0 Deskbook,” Architecture Framework Working Group,
Department of Defense, Washington, D.C., Feb. 9, http://www.dod.mil/nii/doc/docArchive.html#NII
FORCEnet (2005), “Naval Network Warfare Command FORCEnet Homepage,” http://forcenet.navy.mil/
How to List References
If you list the references as numbered and cite them by using numbers, it will be very time consuming and error prone to renumber them when new ones are inserted or some are deleted, unless your document creation software automates it.
Citing references using numbers degrades readability.
It is more readable and more informative to cite references as
[Arthur and Balci 2010; Balci 2001; Nance 2005]
versus
[3, 6, 18]
Seeing the author names in citation clearly indicates whose work you are referring to. When numbers are used, the reader is forced to go to the References section to find out who the authors are.
How to Format References
Publishers adopt different formatting styles. You need to select the one adopted by your publisher.
All references must be formatted according to the selected style in a consistent and complete manner.
Here is a style commonly used:
Web
W3C (2011), “The World Wide Web Consortium,” http://www.w3.org/
Journal
Balci, O. and W.F. Ormsby (2007), “Conceptual Modeling for Designing Large-Scale
Simulations,” Journal of Simulation 1, 3 (Aug.), 175-186.
Book
Pressman, R.S. (2010), Software Engineering: A Practitioner's Approach, Seventh Edition,
McGraw-Hill, New York, NY.
Edited Book
Balci, O., R. Sharda, and S.A. Zenios, Editors (1992), Computer Science and Operations
Research: New Developments in Their Interfaces, Pergamon Press, Oxford, U.K., 536 pp.
How to Format References
In a Book
Balci, O. (1998), “Verification, Validation, and Testing”, In The Handbook of Simulation, J.
Banks, Editor, John Wiley & Sons, New York, NY, August, Chapter 10, pp. 335-393.
In a Conference Proceedings
Balci, O., J.D. Arthur, and R.E. Nance (2008), “Accomplishing Reuse with a Simulation
Conceptual Model,” In Proceedings of the 2008 Winter Simulation Conference (Miami, FL,
Dec. 7-10). IEEE, Piscataway, NJ, pp. 959-965.
Technical Report
Arthur, J.D., R.E. Nance, and O. Balci (1992), “Establishing Software Development Process
Control,” Technical Report TR-92-40, Department of Computer Science, Virginia Tech,
Blacksburg, VA.
Thesis
Alpergin, F. (2007), “A Network-Centric System Architecture for Online Learning
Environments,” M.S. Thesis, Department of Computer Science, Virginia Tech, Blacksburg,
VA, May.
Dissertation
Chigani, A. (2011), “A Campus Situational Awareness and Emergency Response Management
System Architecture,” Ph.D. Dissertation, Department of Computer Science, Virginia
Tech, Blacksburg, VA, May.
How to Cite References
Citations of references must be specified within square brackets using the following format.
References should be cited in the order of importance.
[Pfleeger 2001; Troster and Tian 1995; Kemerer 2010] Separate multiple references by semicolons.
[Balci 1992, 2004, 2011; Arthur and Nance 1998, 2008] Use comma to separate years for publications by the same author(s).
[Arthur et al. 1992] Use et al. for more than two authors. Always italicize et al.
[Arthur 2006b; Balci 2010a; Nance and Balci 2007a, b, c] Use lower case letters to separate publications in the same year belonging to the same
author(s).
How to Cite References
Citations by using the author name(s) directly:
... can be found in Pressman's [2010] book ...
Arthur et al. [2005] enunciate that ...
Examples:
[Tausworthe 1996]
[Dodani 2002; Welch 1999]
[Booch 2007; Dori and Goodman 2011; Boehm et al. 2006]
[Humphrey 2000, 1993a, b, 2007; Munson 2003; Yu and Lamb
1995a, b, c]
[Farr et al. 2005; Welch et al. 2010; Zage 2008]
Difference between References and Bibliography
If you cite all of the references in the body of your document, then the section listing the references must be called References.
If you cite some of the references, but not all of it, in the body of your document, then the section listing the references must be called Bibliography.
You can have a Bibliography in which you mark those references cited by using a symbol such as asterisk. However, that is hard to maintain and must be done just before finalizing your document.
Bibliography is commonly provided in theses and dissertations to show how extensively the literature is surveyed in the research.
Document Quality Perspectives
There are two perspectives of document quality:
Perspective 1: Quality of Document’s Content
Obviously, what ultimately determines the quality of a
technical document is the quality of its content.
Perspective 2: Quality of the Document as a Product
A technical document is engineered as a product and it
must be evaluated as a product.
We use the term “Document Quality” to refer to the
quality of the document as a product.
A technical document must be evaluated as a product
by using a hierarchy of quality indicators before it is
published or released.
Document Quality Indicators
Document
Quality
Accessibility
Accuracy Verity
Validity
Completeness
Consistency
Clarity Unambiguity
Understandability
Conciseness
Maintainability
Portability
Readability
Modularity Cohesion
Coupling
Logical Flow
Presentation
Accessibility
Document Accessibility is the degree to which the document enables its users to easily locate its components in a non-sequential manner.
The accessibility is usually provided by
Table of contents
List of figures
List of tables
Hypertext links
Cross references
Index
All of the above access or navigation aids can be made clickable in an electronic document (e.g., Microsoft Word, PDF, eBook, HTML) to enable the user to automatically jump to the desired location.
Accuracy
Document Accuracy is the degree to which the document possesses sufficient transformational and representational correctness.
It is assessed by
Verity (Verification)
Validity (Validation)
Verity
Document Verity is assessed by conducting document verification.
Document Verification is substantiating that the document is transformed from what it describes into its current form with sufficient accuracy.
Document verification addresses the question of “Are we creating the document right?”.
For example, document verification deals with assessing the accuracy of transforming
a) Research results into a written description
b) Experimentation data into a tabular or graphical form
c) A narrative description into a flowchart representation
Validity
Document Validity is assessed by conducting document validation.
Document Validation is substantiating that the document represents the entity it documents with sufficient accuracy.
Document validation addresses the question of “Are we creating the right document ?”.
For example: Does your thesis describe / represent
a) your research results accurately?
b) the collected data for your research accurately?
c) whatever you developed in your research accurately?
Some Accuracy Indicators
Are all page numbers given in the table of contents, list of figures,
list of tables, or index correct?
Does the table of contents, list of figures, list of tables, or index
correctly name the items listed?
Does the list of figures correctly identify the figure captions?
Does the list of tables correctly identify the table captions?
Does the index correctly name the items listed?
Are there any broken hyperlinks?
Do all hyperlinks access the correct targets?
Do all cross references access the correct targets?
Do all citations of references point to the correct references?
Are all terms defined correctly?
Are all references specified correctly?
Clarity
Document Clarity is the degree to which the document is unambiguous and understandable. It is assessed by Unambiguity and Understandability:
Document Unambiguity is the degree to which each statement, expression, or definition used in the document can only be interpreted one way.
Document Understandability is the degree to which the meaning of each statement, expression, or definition used in the document is easily comprehended by all of its readers.
Conciseness
Document Conciseness is the degree to which compact precise expressions are used without wasted words throughout the document.
Completeness
Document Completeness is the degree to which
a) all components of the document are specified with no
missing information,
b) the document covers all required aspects of the entity it
is intended to document, and
c) the document contains all of the items required by the
documentation standard in effect.
Some Completeness Indicators
How completely are all parts of the document specified with no missing information?
How completely does the document cover all required aspects of the entity it is intended to
document?
How completely does the document fulfill the requirements of the documentation standard in
effect?
How complete is the table of contents of the document?
How complete is the list of figures of the document?
How complete is the list of tables of the document?
How complete is the glossary of terms of the document?
How complete is the list of references in the document?
How complete is the document index?
How complete are the appendices of the document?
How completely are hyperlinks provided where perceived as needed in the document?
How completely are cross-references provided where perceived as needed in the document?
How completely are all acronyms used in the document defined?
How completely styles are used in the document?
How completely are citations of references provided where perceived as needed in the
document?
How completely are all listed references cited in the document?
How completely are all references cited in the document listed?
Do all references listed in the document provide the complete information required to locate
the referenced material?
Consistency
Document Consistency is the degree to which the document uses uniform page layout, notation, terminology, symbology, and format.
Page Layout Consistency: Pages should be laid out consistently in a document. The page layout defines the design and arrangement of the elements of a page.
Notation Consistency: Notation refers to a system of characters, symbols, or abbreviated expressions used to express technical facts or quantities. Notation should be used consistently. Examples:
Characters: X1, X2, X3, ..., Xn
Symbols: m (mean), s2 (variance)
Abbreviated expressions:
pt (point), mm (millimeter), lbs (pounds)
Consistency
Terminology Consistency: Terminology refers to the technical and special terms used in a particular area.
For example, “sample variance” is a technical term used
in Statistics. Its usage should be consistent with its
defined technical meaning in the field.
Symbology Consistency: Symbology refers to expression by symbols and illustrations.
A company logo, an organization's emblem, and a
country's flag are examples of symbology.
Symbology should be used consistently in the document.
For example, the emblems of Air Force, Army, and Navy
should be placed on the cover of a report each with the
same size. Differences in size would be inconsistent and
offensive.
Some Consistency Indicators
How consistently page layout is used?
How consistently notation is used?
How consistently terminology is used?
How consistently symbology is used?
Do all citations of references follow a consistent format?
Are all references listed in a consistent format?
Are all figure captions specified in a consistent format?
Are all table captions specified in a consistent format?
Are all names listed in a consistent format? (Giving the
middle initial of a committee member’s name but not the
others’ is not only inconsistent but also offensive.)
Select a Style and use that Style consistently throughout
the entire document.
Logical Flow
There has to be a Logical Flow from one Chapter to another; from one section to another; and from one paragraph to another.
The document modules must be ordered to establish a logical flow.
Maintainability
Document Maintainability is the degree to which the document facilitates updates and changes.
To accomplish maintainability, you must:
Create and Apply Styles
Insert Cross References
Insert Captions
Use Unnumbered List of References / Bibliography
(unless your software can automate the changes)
Never type anything and manually format it!
Always create and apply Styles to format text!
Maintainability: Apply Styles
Never type anything and manually format it!
Always create and apply Styles to format text!
Maintainability: Insert a Cross Reference
Never enter Figure /
Table / Equation
numbers manually!
Maintainability: Insert a Caption
Figure
Table
Equation
When a Caption is inserted, the number (of the figure,
table, or equation) is automatically maintained by the
document creation software.
Modularity
Document
Chapters
Sections
Subsections
Paragraphs
Sentences
Words
Cohesion
Chapter Cohesion is the extent to which the sections contained in a chapter relate to the topic of the chapter.
The more the sections relate to the chapter topic, the
more the chapter cohesion will be.
Section Cohesion is the extent to which the paragraphs contained in a section relate to the topic of the section.
The more the paragraphs relate to the section topic, the
more the section cohesion will be.
Paragraph Cohesion is the extent to which the sentences contained in a paragraph relate to the topic of the paragraph.
The more the sentences relate to the paragraph topic,
the more the paragraph cohesion will be.
The higher the Cohesion the better it is!
Coupling
Coupling is the extent to which the cross references used in the document are automatically maintained by the document creation software.
Manually creating cross references that are not automatically changed causes the changes to be time consuming and difficult.
Do NOT manually number Figures, Tables, Equations,
and References!
Figure, table, equation, or reference numbers in cross references must automatically change if a new one is inserted in the document.
Manually handling such changes is very time consuming and error prone.
Portability
Document Portability is a quality characteristic of electronic documents and refers to the degree to which an electronic document can be easily transferred from one computer platform to another.
For example, if a document is provided in Portable Document Format (PDF) or in Hypertext Markup Language (HTML), the document is considered to be very highly portable.
Document portability in other formats such as postscript, Microsoft Word, and Rich Text Format (RTF) should be judged according to the format's availability to the intended user community.
Portability
The portability quality characteristic may conflict with others such as readability, accessibility, and maintainability.
For example, the most portable document format is plain text, but it has the worst readability characteristic.
I hate Plain Text E-Mail!
It hurts my eyes, and reminds me the typewriter age!
But yet, it seems to be mostly used!
The PDF is very highly portable but it is not as maintainable as the Microsoft Word format.
Therefore, the PDF is commonly used for document distribution while the document is maintained in its original format (e.g., Microsoft Word).
Presentation
Presentation Quality is the extent to which the document is visually appealing to the human eye.
Presentation quality is influenced by
Document layout
Formatting
Physical composition
Readability
Readability is the degree to which the document enables its reader to easily read and understand.
Readability is influenced by the following indicators:
Page Layout defines the design and arrangement of the elements of a page.
It is considered to be the most significant factor
affecting the readability of a document.
Structuring the layout of a page is considered to be an
art.
Highlighting important elements of a page increases the readability of a document.
Highlighting is commonly provided by using font styles
such as larger font size, font color, bold, italic,
underline, double underline, overline, strikethrough,
change bar, and small caps.
Readability
Usage of Fonts
The size (e.g., 10, 11, or 12 point), family (e.g., Times
New Roman, Helvetica, Courier), typeface (e.g., plain,
bold, italic), and color of a font affect the readability of a
document and should be selected properly.
Commonly, the Times New Roman font is used for the
body text and the Helvetica or Arial font is used for
headings in a technical document.
The Courier font is a disproportional font, i.e., each
character has a fixed width occupying the same amount
of printed space, and is commonly used for computer
program listing in a document.
For example, a computer program listing in the Times
font is more difficult to read than in the Courier font.
Naturally, a small font size is difficult to read but a very
large font size is also difficult to read.
Usage of Figures and Illustrations
As indicated by the phrase “a picture is worth a
thousand words”, the proper use of figures (e.g.,
charts, diagrams, drawings, graphs, illustrations)
increases the readability of a document.
Usage of Tables
Presentation of some material in a tabular format
increases the readability of a document.
Usage of Case
Proper usage of case (e.g., title case, sentence case,
lowercase, uppercase) increases the readability of a
document.
Text in all capital letters is known to be difficult to read.
Avoid using text in all caps!
Readability
