How to become an API technical writer

A fellow technical writer asked me recently if I had any tips about becoming an API technical writer. That’s someone who writes developer-focused documentation, describing the application programming interfaces (APIs), software developer kits (SDKs), and other tools that developers use to make one application talk to another. This post has some tips I can share. If you have any more ideas, I’d love to see them too.

My 2c: In doing developer-focused documentation, there’s the writing side, the technology side, and the “attitude”.

The writing

The writing side isn’t all that different from user-focused technical writing. You’re telling people how to use something. In this case, it’s an API or SDK or other tool.

A while ago, I asked some respected developers about their favourite technical documentation sites. The results are in this post: What developers want. There are some useful links in the post and in the readers’ comments. Another post describes a project to build a developer documentation wiki, and also has some useful links and tips.

Stack Overflow has some good information about writing API documentation. Try a search, and pick the answers that suit you. For example, Best ways to document use of an API and What is the best way to document an XML-RPC API.

The tech

On the technology side, you need to know the basics of web technology: HTML, CSS and JavaScript. W3Schools offers some good courses, free of charge, to get you started, or refresh dormant knowledge.

If you’re aiming to work at a particular company, find out what technologies their developers use, and get to know those well. It’s also good to pick a widely-used programming language, such as Java or C++, and do a basic programming course so you know what it’s all about.

Different companies have varying requirements for their API technical writers. In some companies, the bar is set quite high – you’ll need to be able to write your own code samples and review the code written by the developers. In other companies, it’s enough just to read code.

The attitude

A developers’ technical writer needs to love APIs and SDKs. As far as you are concerned, they are the future of the universe. Immerse yourself in the concepts, and fly with the buzz words. Know what the cool kids are doing. Play with the technologies.

Hacker News (HM) is a popular discussion site for devs. Drop in regularly on the Hacker News Daily, to see the most popular topics of the day. HN has a good mix of tech topics, engineering of all sorts, political, social, and more. At first the tech topics will be foreign to you, but after a couple of weeks you’ll start pulling technologies together nicely.

Experiment with some APIs – Google Maps, for example

There are some great APIs to play with. Getting to grips with one or two will teach you about APIs and their accompanying documentation.

For example, try the Google Maps JavaScript API. Of course, I have a soft spot for it, because I’ve just started working on the documentation. But I think it would make a good API to start with. It’s fairly approachable: if you use Google Maps, you’ll recognise the features offered by the API. And you can use the API just by building an HTML page in a text editor, and copying and pasting the sample JavaScript from the tutorials. It’s fun and satisfying to see your very own map taking shape, with the full power of Google Maps as a base.

More tips?

How about you – do you have any advice for up-and-coming API technical writers? For example, I tried to think of a good book to recommend, but nothing sprang to mind. All ideas welcome!