The Art of Technical Documentation

Contents

About this Book


1 Technical Documentation Defined

Types of Technical Documents

Quality in Technical Documentation

Accuracy

Completeness

Usability

Clarity

Readability

Logical Progression

Conciseness

Appropriateness of Language

Grammaticality

Appropriateness of Content and Scope

Appeal of Package

Further Reading


2 A Career in Technical Documentation

Example of a Project Team

Writing Tasks

Career Growth in Technical Documentation

Documentation Management

The Singleton Operation

The Separate Writing Group

Part of Engineering

The Outside Documentation Consultant

Further Reading


3 Precepts of Technical Documentation

Work Methodology

Know Your Subject

Technical Concepts

Use of Technical Experts

Know Your Reader

Writing for the Novice

Writing for the Experienced User

Writing for the Computer Operator

Writing for the System Manager/Administrator

Writing for the Information Systems Manager

Writing for the Programmer

Writing for Other Industries

Writing Technical Reports and Marketing Literature

Your Technical Training

Know the Rules

Organization of Material

Format Considerations

Categories of Technical Documents

Organizational Elements of Technical Documents

Terminology

Style

Know Your Tools

Further Reading


4 Development Techniques

A Typical Writer's Workplan

Sample Writer's Workplan

The Quality Documentation Process

Research

Understanding

Planning

Writing Your Documentation

Reworking Your Documentation

Receiving the Results

Further Reading


5 Graphics in Technical Documentation

How to Prepare Graphics

How to Use Graphics

How Not to Use Graphics

How to Place Graphics on Your Page

Visualization

Further Reading


6 Information Presentation

The Great Attractors of Technical Documentation

Page Layout

Page Details

Reader-Level Formats

Readability

Punctuation in Technical Documentation

Special Notation

Tables

Book Design

Typography

Printing

Types of Paper

Bindings

Screen Layout

Combined Media

Information Retrieval

Hypertext Systems

Human-Computer Interfaces

Alternative Media

Further Reading


7 Tools

Text Editors

EDT

EMACS

TeachText

LSE/TPU

Graphics Editors

DECwrite

Adobe Illustrator

Micrografx Designer

Support for Information Structures

Text Formatting Software

DSR/troff/dtroff/nroff/RUNOFF

Scribe

Tex

Page Layout Systems

Vax Document

Interactive Page Layout Systems

Interleaf

PageMaker

Language Tools

Electronic Dictionaries

Spelling Checkers

Grammar Checkers

Translation Aids

Language Analysis Tools

Software System Tools

System Features

Code Management Systems

Specialized Authoring Tools

Further Reading


8 Computer Hardware

System Hardware

Personal Computers

Workstation Systems

Minicomputers

Mainframe Computers

Feature Comparison of System Hardware

Input Devices

Keyboards and Mice

Imaging Systems

Scanning Devices

Output Devices

Printers

Video Screens

Hardware Used to Create Your Book

Further Reading


9 Conclusion

A Societies, Conferences, and Journals

Societies

Conferences

Journals and Magazines

B Standards

C Timeline of the Development of Writing

Glossary

Select Bibliography

Index