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). As a little extra safety cushion while you’re working, you may consider downloading a grammar tool, and this grammarly review might help you decide if something like this would help – our eyes alone are not always enough.
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 [email protected].