Archive for February 2009
The Future of Documentation Belongs to XML, Extended Markup Language
Introduction XML, that is, Extended Markup Language, is the future of technical writing. Two Reasons There are TWO important reasons why that is so. REASON 1: XML is at the heart of “single sourcing” movement. The whole idea is to write something once and then “tag” it in such a way that it would be…
Read MoreA Top Copywriter on the Importance of Loving What You Do
by Bob Bly www.themillionairewriter.com In his book “Confessions of an Advertising Man,” David Ogilvy quotes an old Scottish proverb about happiness: “Be happy while you’re living, for you’re a long time dead.” The idea is that you should do everything in your power to be happy now, because tomorrow you might not be here. Given…
Read MoreWhen 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 MoreHow to Set Up a "Media Room" for Your Small Business Web Site
Set up a Media Room (MR) for journalists visiting your Small Business web site. A Media Room will jack up the traffic to your sales, event sign-ups, or membership subscriptions by offering all the necessary easy-to-use copy and photos for the editors and producers who are on a deadline. A journalist or an editor visiting…
Read MoreTechnical 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 MoreTechnical Writing – How to Use the Bulleted Lists Properly in Your Technical Document
© Ugur Akinci Bulleted lists are important in technical writing. They summarize information in a manner that is easy to read and absorb. Use them whenever you can to get your information across quickly. Bullets are ideal for things-to-do, equipment, sets, collections, cooking ingredients, and all kinds of other lists. Compare: “In winter months make…
Read MoreHow 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 MoreTechnical 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
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 MoreTechnical Writing – What Does it Take to Become a Technical Writer?
For one thing, you really do not need to be an artistically creative person to become a technical writer. Forget about plot, dialog, character, original concept, etc. Actually someone quipped “if it ain’t boring then it ain’t tech writing.” That’s harsh but there is some truth in it too. Technical writing is certainly not about…
Read More