How to Write Effectively
At its core, good technical writing is simply good writing about technical topics. If you are approaching this field from a writing background, you may already know the basics of good writing but need to learn more about the technology. If you are an engineer or developer, perhaps you haven't exercised your writing muscles in awhile. Here are some general guidelines for producing clear, understandable, readable writing that will help your readers gain the information that they need.
Clarity and Simplicity
Write like You Talk
Sometimes people think that written communication should not resemble spoken communication. If you're taking the trouble to write it down, the thinking goes, shouldn't it be more formal, more serious? In a word, no, especially when you are working to explain complex subjects in an understandable way. Good, clear writing is a lot like talking, but without the pauses, Ums, ahs, and "ya knows." In fact, if you prefer face to face communication to writing, you may prefer to do your writing with your voice and a voice recorder, dictating the points you would like to get across, and then transcribing and editing them later. Plenty of accomplished writers work this way.Get Straight to the Point
If you're writing the section of the user's manual that tells the user how to turn the product on, show the user a picture of the on/off button, note in the text where the button can be found, and then write "Turn the power button on." The user doesn't need to know that turning on the power button closes an electrical circuit, causing current to flow. They don't need to hear that the original design called for the button to be on the right side and now it is on the left. They do not need any information on the history of power button design. They simply need to know where the button is and what it does. This example may sound facetious, but it is good to remember the user's needs when writing documentation. If your content doesn't help the user operate the product, then you aren't doing your job.
In print manuals, space is often limited by the constraints of the printing process and the cost of paper, so excess verbiage is kept out of manuals for cost reasons as well as for editorial ones. With more and more help online now, the demands of space are theoretically eliminated, since web pages can be almost infinitely long. But it is more important than ever to get straight to the point. Readers on the Web tend to skim, hoping to find the information they need quickly and then move on. If you can answer their questions in the first paragraph of your help file, then their needs will have been served and you've done your job well. Always think of your user, and remember to respect his or her time.
Simplify
One of the challenges of technical writing is to simplify complex topics without oversimplifying. This is where putting yourself in the user's place can be helpful. How much does the user need to know about this aspect of the product's operation? Are you giving him enough information without overwhelming him? When in doubt, it is probably better to err on the side of simplicity. One method of simplifying complex topics, and of helping users relate to a new piece of equipment or software, is by drawing an analogy to something that they are more familiar with. Instructors explaining the flow of electricity often draw comparisons with the flow of water through pipes. Technicians explaining machine maintenance often compare their machines to cars, which nearly everyone knows something about operating and maintaining.]]>