Writing: clarify, explain, and persuade
Technical writing can make for the most boring reading ever—until you’ve got to fix a technical problem in a software application or a production line, or follow a detailed set of installation instructions. Then the procedure you’re reading becomes the most devilishly interesting thing there’s ever been.
The best technical writing cuts out as much fat as possible and focuses on getting the reader where they want to go—to the end of the procedure.
There are a lot of less than helpful ways to do this, such as chatting away idly to the reader. For instance:
“The first thing to do once you’ve opened the application is choose the standard installation, and then go to the next button and click on it to go to the next screen, where you can decide where to install Linguation.”
- Click Open. The installation wizard opens.
- Click in the Standard installation checkbox.
- Click Next. The Choose a Location screen opens.
Now don’t get me wrong. We don’t need to be all Calvinist. But there’s a big difference between being user-friendly and being needlessly chatty.
There are a whole slew of elements that will need to be decided on in any piece of technical writing: How are bulleted lists to be handled? Are sublists acceptable? What about capitalisation of each bulleted item? Are sentences and fragments allowed in the same list? (The general answer should be no.)
If all or most of these decisions have been made, it can simply be a matter of implementing them. But if standards are out of date, or if none have been established, a style guide may be needed.
For more on styles guides, please visits the style guides and training page.
To see examples of technical documentation, check out the samples page.