How to improve my technical writing?
August 3, 2013 9:03 AM Subscribe
I'm in a creative portion of the software development field (advertising), and I often am asked to help write technical documents like case studies, final documentation to the client or simply find myself needing to explain technical ideas to a client. How can I improve my writing skills? I'm looking for general tips or rules, as well as examples of engaging technical writing that doesn't read like a Github Wiki page.
In the interest of being correct I often find myself being too technical and dry in my writing. I call internet troll fatigue, I'll often distill things down to a point where my writing looks like legalese. This is good to an extent, but I really want to improve my writing and make it more accessible. Something similar to this is what I'm looking for. Thanks!
In the interest of being correct I often find myself being too technical and dry in my writing. I call internet troll fatigue, I'll often distill things down to a point where my writing looks like legalese. This is good to an extent, but I really want to improve my writing and make it more accessible. Something similar to this is what I'm looking for. Thanks!
Developing Quality Technical Information is my favorite technical writing book. It's well-organized, so you can easily skip topics that might not interest you (like content management).
The Microsoft Manual of Style is probably the resource that most American technical writers use. You can find lots of tips and tricks in it. The latest edition is the fourth, but Microsoft offered the third edition for free for a while, so you may still be able to find it online.
Cherryleaf and Scriptorium are two firms that offer a lot of resources (free and paid) to new and experienced technical writers. You may find their webinars helpful.
Two trends that you might look into are minimalism and Simplified Technical English.
posted by neushoorn at 12:40 PM on August 3, 2013 [3 favorites]
The Microsoft Manual of Style is probably the resource that most American technical writers use. You can find lots of tips and tricks in it. The latest edition is the fourth, but Microsoft offered the third edition for free for a while, so you may still be able to find it online.
Cherryleaf and Scriptorium are two firms that offer a lot of resources (free and paid) to new and experienced technical writers. You may find their webinars helpful.
Two trends that you might look into are minimalism and Simplified Technical English.
posted by neushoorn at 12:40 PM on August 3, 2013 [3 favorites]
I write user-facing copy for a number of software platforms, and my general rules are:
- Keep the tone friendly (Feel free to use “we” and “our” rather than “The Company” all the time).
- Use active voice over passive as much as possible (“We developed…” > “This technology was developed…”).
- Make the whole document as short as you can, with easy-to-scan bullet points and sub-headings (i.e. chunk your info).
- Avoid jargon – don’t use the insider technical term if there’s a real world equivalent (or use “the Jargonator 3000” on first use and “the device” every time after).
- Maintain parallel structure throughout (all lists start with verbs, for example).
- Put things in simple charts, graphs or diagrams if you can. People love to scan for these.
You might want to take a look at some consumer product user guides such as those for DSLRs (my Nikon D3200 came with a well laid out user guide) for tone and structure.
Good luck!
posted by LynnDee at 12:46 PM on August 3, 2013 [2 favorites]
- Keep the tone friendly (Feel free to use “we” and “our” rather than “The Company” all the time).
- Use active voice over passive as much as possible (“We developed…” > “This technology was developed…”).
- Make the whole document as short as you can, with easy-to-scan bullet points and sub-headings (i.e. chunk your info).
- Avoid jargon – don’t use the insider technical term if there’s a real world equivalent (or use “the Jargonator 3000” on first use and “the device” every time after).
- Maintain parallel structure throughout (all lists start with verbs, for example).
- Put things in simple charts, graphs or diagrams if you can. People love to scan for these.
You might want to take a look at some consumer product user guides such as those for DSLRs (my Nikon D3200 came with a well laid out user guide) for tone and structure.
Good luck!
posted by LynnDee at 12:46 PM on August 3, 2013 [2 favorites]
This thread is closed to new comments.
If that doesn't work, do it out loud, typing along with yourself talking. Keep talking as you type. This forces you to keep moving rather than parse every word and include every detail. If you have to stop talking to take a breath, end the sentence.
posted by Etrigan at 10:20 AM on August 3, 2013 [1 favorite]