Improving Your Technical Writing

I receive a number of e-mails each month from people who want to improve their technical writing skills. Most of the people who write are in a technical trade, but not writers by profession. For example, I might get an e-mail from a software engineer or an IT manager who needs to write better reports. Of course, the primary way to improve your writing is to practice. A good friend of mine expresses this idea in Make Writing a Habit. It’s good advice. No matter how much talent you might possess, you can’t become good at something until you practice (often, quite a lot).

Practicing applies to any sort of writing, but technical writing has a few special requirements that you need to consider. The first rule of good technical writing is to ensure you know what you want to say. This means creating an outline, even if you’re working on an article length project. In some cases, you won’t even use the headings you create as part of the resulting piece—the headings are there to keep you on track and focused. The more detailed you can make your outline, the better your writing will go.

Creating an outline doesn’t guarantee any sort of success, unfortunately. People often see a heading and can’t quite remember what they planned to put there. It’s a common problem, so you shouldn’t worry about it. What you should do instead is provide notes to yourself on what you plan to put into a heading. I often include URLs for sites that I want to review in depth or provide as part of my piece right there with the notes. If you got an idea for something you’d like to do by reading some resource, make sure you include a specific reference to that resource as well (never plagiarize though—always create your own text from the sources you use).

In depth research is also a huge part of writing technical documents. Keep thinking about what you want to write and verify every fact by researching it in some way. In some cases, research includes creating an experimental setup on your own system. This may sound like a lot of work, but it’s often the best part of technical writing. Experimenting to find out whether some idea will actually work is fun and interesting. It’s also time consuming, so make sure you plan ahead if you want to perform some experiments as part of creating your piece.

All of these approaches will help improve your technical writing. However, the biggest mistake that many technical writers make is writing for themselves, rather than for their target audience. You have to put yourself in your reader’s shoes and answer the sorts of questions your readers will have. Role-playing may not seem like part of technical writing, but it is. You have to put on your reader hat to be successful. In some cases, getting the reader hat on right is nearly impossible, which is why I also rely on beta readers to read my material. These people ask questions I’d never think of even if I spend weeks trying to do so.

Technical writing is about organized and succinct content. It’s about creating a flow of ideas from your mind to the reader’s mind through the medium of the written word. You’re a teacher of sorts, but your classroom is vast and you’re not able to speak with your pupils. To write good technical documentation you have to think about the sorts of questions your reader will ask or find someone who will ask them for you. The outline, research, and roll playing all come together to help you create a document that conveys information to your target audience in a unique manner that reflects your particular philosophy of solving technical issues.

Creating good technical documentation is something that most people can do with enough practice, thought, and research. Knowing your audience is an essential part of any kind of writing, but with technical writing it’s an absolute necessity. Let me know your thoughts about technical writing at John@JohnMuellerBooks.com.

 

Author: John

John Mueller is a freelance author and technical editor. He has writing in his blood, having produced 99 books and over 600 articles to date. The topics range from networking to artificial intelligence and from database management to heads-down programming. Some of his current books include a Web security book, discussions of how to manage big data using data science, a Windows command -line reference, and a book that shows how to build your own custom PC. His technical editing skills have helped over more than 67 authors refine the content of their manuscripts. John has provided technical editing services to both Data Based Advisor and Coast Compute magazines. He has also contributed articles to magazines such as Software Quality Connection, DevSource, InformIT, SQL Server Professional, Visual C++ Developer, Hard Core Visual Basic, asp.netPRO, Software Test and Performance, and Visual Basic Developer. Be sure to read John’s blog at http://blog.johnmuellerbooks.com/. When John isn’t working at the computer, you can find him outside in the garden, cutting wood, or generally enjoying nature. John also likes making wine and knitting. When not occupied with anything else, he makes glycerin soap and candles, which comes in handy for gift baskets. You can reach John on the Internet at John@JohnMuellerBooks.com. John is also setting up a website at http://www.johnmuellerbooks.com/. Feel free to take a look and make suggestions on how he can improve it.