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 started his career as a part-time computer technician in 1994, worked his way up to system administrator by 1997, and has specialized in vulnerability management since 2013. He invests in real estate on the side and his hobbies include O gauge trains, baseball cards, and retro computers and video games. A University of Missouri graduate, he holds CISSP and Security+ certifications. He lives in St. Louis with his family.