[p8952]

>You start with a background in English or professional writing and learn the technology, or you can start with a computer science degree or something similar and learn how to write.

Could you please recommend some good resources for learning to write, in the context of technical writing or more generally?

[karlb]

I write for a living (conversion copywriting). My favorite resources are all at the bottom of this article my colleagues and I wrote:

http://www.conversion-rate-experts.com/writing/

I absolutely love the first half of the one by Stephen Wilbers (Keys to Great Writing):

http://www.amazon.com/Keys-Great-Writing-Stephen-Wilbers/dp/...

[mcone]

Different people will give you different answers, but I always advise people to do three things: study writing samples, find mentors and nurture relationships with them, and practice writing on your own.

The first item is really easy. Just go out and find companies that have documentation that you like. You'll probably find you like the way some technology companies write docs -- I personally like the documentation provided by Heroku and Apple -- but you can find good documentation in other places too. Study these docs! Read them again and again. Try to to soak it up like a sponge. After a while you'll start noticing patterns in how they use language and how they organize the information. Just as important, of course, is studying documentation that you don't like. Try to figure out why it doesn't work and then avoid making those mistakes in your own documentation.

Finding mentors is a little more difficult. I cold emailed several authors back when I was started out and almost all of them responded and provided a lot of help. Owen Linzmayer, an author at No Starch Press, responded with this advice: "The most important thing to remember about technical writing is that the goal is not necessarily to be understood, but rather to avoid misunderstanding. As such, consistency and clarity are paramount, and you should never assume your reader has the knowledge you possess. I try to make sure to tell readers not only how to do something, but why. That way they are not just following instructions and learning by rote, but rather, they're building their understanding of the system you're explaining, and perhaps can devise solutions to problems you haven't covered." I also emailed author Robin Williams, and she invited me out to lunch. She was kind enough to have me do some ghost writing with her on a book at Peachpit Press. You need these kind of breaks to learn the ropes and get into a position where you can author books and work in the industry full time.

Obviously practice is really important. The best thing to do is probably create or contribute to some kind of blog or open source guide about something you know. There are plenty of them out there. The Hitchhiker’s Guide to Python (http://docs.python-guide.org/) comes to mind. Keep working at it. It's frustrating and difficult work, but you'll get better over time. In many ways learning to write good technical documentation is just as difficult as learning to code.

Another thing you'll want to do is find a good style guide. Microsoft has one, as does Apple. Apple's is available for free: https://help.apple.com/asg/mac/2013/ASG_2013.pdf