Technical Writing
How to Write a Terrible Technical Document
© 2010 Ugur Akinci There are many ways to write a really bad technical document. Let’s look at some of the foolproof ways to accomplish that. (1) Obtuse or indecipherable document title Instead of calling your document “Mark-24 User Manual”, use one of the following titles: “M24/X-768 Set-5.3 Rev. 4.4.6.8 OPS-VII H4G5” Or “The All-Comprehensive…
Read MoreHow to Gain the Respect of the Developers & Engineers in a Software Company
© 2010 Ugur Akinci Here is an important article that all technical writers should read; especially those who work or would like work for a software company. The article, written by Eric J. Ray, obviously an industry veteran who knows what he’s talking about, addresses an important issue rarely discussed this openly: for various reasons,…
Read MoreA Free Help File Software: HelpNDoc
© 2010 Ugur Akinci My readers know my fondness for Adobe RoboHelp for creating help files. But for those who cannot afford RoboHelp there are some free alternatives out there like HelpNDoc; free at least for personal use. If you need to use these programs commercially you may need to pay a small licensing fee,…
Read MoreHow to Shift from a Career in Pharmaceutical Sales to Medical Writing
A reader wrote asking what to do and in which direction to go in shifting from a career in pharmaceutical sales to writing. I’m sharing my answer here since it may benefit all my other readers who also find themselves in a similar situation: “The fact that you’re coming from sales should be a positive…
Read MoreHow to Create an Index for an Adobe FrameMaker Document
Creating an index for an Adobe FrameMaker document requires two steps: marking the index entries, and then generating the index. To Mark the Index Entries 1) Launch FrameMaker 9 and open your document. 2) Select the text that you’d like to mark as an index entry. 3) Select Special > Marker from the main menu…
Read MoreTechnical Book Review: "How to Write Usable User Documentation"
How To Write Usable User Documentation (Second Edition) by Edmond H. Weiss is a thoughtful book on technical documentation written by a professional who obviously knows his material very well. Yet, overall, from its content to its format, this is also a book that shows its age. Published back in 1991, many of the topics…
Read MoreWhat is “Optimal” and “Optimization” in Technical Communication?
© 2010 Ugur Akinci From time to time I see sample documents in which the terms “optimal” and “optimization” are not used correctly. Since it’s a term that’s frequently used, I’d like to address it for the benefit of those TCC readers who wrote to me asking for an explanation of the concept. For one…
Read MoreHow to Write About Circuit-Board DIP Switches
© Ugur Akinci DIP switches are electronic components frequently used on circuit boards (a.k.a. “motherboards”, “panels”, “control boards” or “controller boards”) to configure basic system behavior by keeping a circuit either open or closed, by default. Once you set the value of a DIP switch it remains the same until you change it manually. First…
Read MoreTechnical Book Review: Studying Engineering: A Road Map to a Rewarding Career
If you’re a parent with a high-school kid who is debating whether to become an engineer or not, say this to him or her: “Here, read this book first and then decide on whatever you want to be…” The book I’m referring to is STUDYING ENGINEERING: A Road Map to a Rewarding Career by Raymond…
Read MoreThe Hidden High Cost of Cutting Down on Documentation
© 2010 Ugur Akinci When times are rough, one of the first things companies try to cut back on is documentation. Some managers believe that if they fire a few technical writers and skip on user and installation manuals the company would make more profit. The reality could be just the opposite. The company may…
Read More