Hacker News Reader

If I can ask...what do you make as a technical writer relative to what you could be making if you were an average person doing the actual technical job, e.g. what is the work and wage like to write about JavaScript as opposed to being a front-end developer at the average tech company?

The ratio, from knowing the approximate range of what my technical writer friends make, is probably around 50-75% (depending on experience).

However, technical writers who write books can share in an income stream, an advantage in the long term.

I think wallflower is right: Technical writers generally get paid less than what developers make. But every company is different. At Compose.io, for example, I think it could be more of a blended position, which is to say that you could be writing documentation and contributing to the codebase [1]. There may not be much of a pay gap at companies like that.

There are also other benefits. Technical writing positions are generally extremely low stress jobs where you have ample time to finish your work, learn new technologies, etc. And as I mentioned before, many of these positions are remote, so you have the opportunity to live in places with low costs of living.

[1] https://compose.io/jobs/#technical-content-creator

>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?

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

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/...

Thanks for your insight and encouragement. I actually studied compsci and creative writing, so I have a background in both. I am still working as a software developer / "data engineer" by day, and I am starting to sketch out a small book by night.