Technical Writing
How to Write a Documentation Plan
Documentation Plan is one of the key documents in technical writing. When starting off a technical communication project, either as a freelancer or a payroll employee, you’d better start with a Documentation Plan to avoid any unnecessary complications and headaches down the road. Here are the ideal stages of any documentation project: 1. Write the…
Read MoreTechnical Book Review – "The User Manual Manual"
© Ugur Akinci The User Manual Manual : How to Research, Write, Test, Edit & Produce a Software Manual by Michael Bremer (Untechnical Press Books for Writers Series, 1999, 314 pp) is a useful text book to learn not only the techniques of producing a software manual but becoming more aware of the “organizational ecology”…
Read MoreHow to Avoid Information Overload in Technical Writing
Too much information can be as bad as too little information in technical writing. Too little information prevents us from understanding the context and relationships. For example: “The motherboard failed the temperature test.” Yes, but in what way? Did it fail in the lower temperature zone or the high end of it? How long did…
Read More
How not to Sacrifice Clarity to Simplicity in Technical Writing
Introduction Simplicity in technical writing is a mantra frequently repeated by trainers and writing instructors. You’ve heard it many times and in general, it’s true: “Write simply. Eliminate all unnecessary words and facts from your technical writing.” Plain language is of course what we all like. But there are always exceptions in life, including this…
Read MoreHow to Write an "Architectural and Engineering Specifications (A&E)" Document
If you think A&E stands for “Arts and Entertainment” TV channel you’re correct. But it also stands for a frequently used technical document: “Architectural and Engineering Specifications (A&E)“. The adjective “architectural” here of course has nothing to do with buildings. It denotes the way something is designed and structured. It’s used in the generic sense…
Read MorePostmortem Analysis of a Technical Writing Project
© Ugur Akinci A postmortem analysis of any technical writing project is a crucial part of the whole project. It’s the closure that reveals the strengths and weaknesses. After we finish a project we should make a habit of analyzing what went wrong during the project and what didn’t, and how we can improve our…
Read MoreHow to Write a "Read Me" file
© Ugur Akinci A “Read Me” file is a part of almost every software product, whether it’s released on a CD (and marketed in a box) or downloaded from the Internet. It traditionally has the file name ReadMe.txt or Read_Me.txt and consists of an unformatted plain text file. The idea is to make sure it…
Read MoreHow to Become a "Software Development Kit" (SDK) Technical Writer
© 2010 Ugur Akinci SDK (Software Development Kit) (a.k.a. “devkit”) writing is a highly specialized hi-tech niche within the technical communication field. The pay and the benefits are good but the entry threshold is high. This well-paying technical writing specialty is not for the beginner-level tech writers or those who do not have a good…
Read MoreHow to Write a Service Level Agreement (SLA)
A “Service Level Agreement” (SLA) is one of the dozens of document types created regularly by technical communicators, usually under the supervision of the corporate legal departments. An SLA is typically issued by a technology service company to regulate its business relationship with the customer, or end-user. Web-hosting companies and SAS (Software as a Service)…
Read More4 Levels of Editing in Technical Writing
Writing is re-writing; that is, editing. Technical editing is a crucial part of all technical writing projects. But we have to remember there are multiple levels of technical editing which makes the task all the more challenging. LEVEL 1 EDITING Spec Editing. Does the document satisfy all the macro requirements specified in the Documentation Plan?…
Read More