I saw this piece by Steve Losh last week, and thought it was some of the best advice about writing I’ve seen in a very long time. Programmers don’t generally like to write, but I find if you tell them how, they can do a good job of it. It’s much easier for a programmer to learn to write than for a writer to learn how to program. Losh does a good job of telling how.
But beyond that, I think it’s a good reading assignment for anyone who writes documentation of a technical nature. I’ve worked with some very good writers and some very bad writers over the course of my education and career, and this would have helped both types. It would have made the good ones better and the bad ones at least marginal. The thing about writing is that if you know the rules and you follow them, it doesn’t take much else on top of that to be good.
So, if you ever get stuck writing documentation–and if you’ve been reading me for many years, I’d say there’s a pretty good chance you do sometimes–give this a read. It will help you get into the mindset you need to be in, and write more effectively. Even if you’re not a programmer. Because, even though he’s a programmer, he uses cars and guitars as his examples. So if you were writing about how to build a bookcase, his instructions would help you.
David Farquhar is a computer security professional, entrepreneur, and author. He has written professionally about computers since 1991, so he was writing about retro computers when they were still new. He has been working in IT professionally since 1994 and has specialized in vulnerability management since 2013. He holds Security+ and CISSP certifications. Today he blogs five times a week, mostly about retro computers and retro gaming covering the time period from 1975 to 2000.