When to Use Jargon in a Technical Document?

Introduction As a technical writer you’ve heard this piece of sage writing advice a thousand times: you should stay away from jargon and write as you speak. It’s basic. Strunk & White said so, didn’t they? It’s true. But is this rule true ALL the time, unconditionally? No, I’m afraid it is not. Life has…

Read More

Technical Writing – How to Edit a Technical Document?

Imagine you’re a technical writer looking over my shoulder as I’m editing a technical manual. This is how I’d do it: ORIGINAL: “Logging in involves the Operator typing in his User ID and Password.”BETTER: “To log in, the Operator must enter a valid User ID and Password.” ORIGINAL: “The operator’s assigned authorities for operating, configuring…

Read More

How to Improve Your Technical Copy by Editing "Trash Can Sentences"

You can improve your technical copy instantly by staying away from sentences with a long RANDOM list of objects. I call them “trash can sentences.” Here is a technical copy example: “The Committee will meet Thursday morning to discuss building permits, hiring practices, derivatives trading, inventory, Thanksgiving recess, product modeling, labor issues, Caribbean resorts, IPO…

Read More

Technical Documentation of "Quality Management" Projects

© Ugur Akinci “Quality Management” is yet one of the many employment opportunities available for technical writers today. If you have not heard of QM before, here is a great blog entry by Irv Boichuk explaining the concept and how it relates to technical writing very well: A technical writer is indeed an excellent person…

Read More
Parallel Construction in English

How to Write a Great Index for your Technical Document

Introduction An index, as we covered in our pillar post on indexing, is a list of terms in your technical document that points to the location of the term within the document. In a printed book, an index typically appears on a separate page, often near the end. It is an alphabetical list of words…

Read More

Technical Writing – Make $62,780 a Year as a Technical Communicator

© Ugur Akinci I did not make up the annual income figure in the headline. That is the Average Annual Wage earned by technical communicators across the United States in 2007 according to the “2007 Technical Communicator Salary Survey” conducted by Society for Technical Communication. For example, in California, technical writers made as low as…

Read More

Technical Writing – VAED Method to Document a GUI Element

In database applications, CRUD is an important principle to observe. It is an acronym that stands for: Create (C) [i.e., connect to] database Read (R) database Use (U) data Destroy (D) [i.e., disconnect from] database When documenting the features of a GUI (Graphic User Interface), there is a similar ACRONYM that can help you create…

Read More