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!
Posted on 17 August 2013, in APIs, technical writing and tagged API documentation, technical communication, technical documentation, technical writing. Bookmark the permalink. 22 Comments.
ffeathers 
I think the best way to be a technical writer that writes developer documentation is to write some developer documentation. This is less obvious than it sounds. A good way to start would be to write a tutorial for some API, even if there’s already one or more tutorials available. It’s good practice for the writer, both as a matter of writing and of understanding the software. Another route is to make something and then document it. I did this recently with a ludicrously simple open source Python library that I wrote, but it was still warmly received and good practice writing docs and Python.
Another good way to learn the technologies is to go to meetups for stuff you’re interested in. When I lived in Washington, DC, I loved going to the DC Python Meetup. I was sometimes out of my depth, but I learned something new, interesting, and useful every time. (And I even got to give a presentation myself about creating documentation, so there was give as well as take).
Hallo ddbeck
Great points. There’s nothing like getting your hands dirty, both for the practice and to see how you like the job. Kudos on your open source Python library!
Cheers
Sarah
Hi,
Thank you for these tips.
Would you know of any open-source sites that need developer documentation? I would like to create documentation that does not exist yet, and have developers evaluate if it serves their needs.
Great approach, very helpful.
Sarah
This would make an excellent presentation for the STC Summit next year in Phoenix, AZ! I’d certainly attend the session.
Hallo Melissa
Thanks! You read my mind. 😉 I’m putting together a proposal on this topic at the moment. I’m thinking of including an introduction to APIs and other developer products that we may be asked to document. And some tools that are useful to know about. Its great to know you’d be keen on attending such a session.
Cheers
Sarah
Two fundamentals in my experience are emulation and use cases.
With the emulator you can use and describe how to use the API/SDK.
With the use cases you can suggest business requirements that developers can produce solutions for. Use cases are usually provided by product management from a requirements specification.
Lacking such help, with Google Maps or any other API/SDK I would think about an application I would like to see, specify its business/commercial requirements or use case, then describe how to produce it.
Its benefits need to be put in there somewhere as well.
Hope this helps.
Hallo pencred
Thanks for the great tips. Emulators are an essential part of a tech writer’s toolkit. Especially if you’re working On a product that supports a number of platforms. I’ve made a note to add this to my presentation.
Use cases are important too. Sometimes we even have the luxury of having many different use cases, and we can work with the product managers to pick the most meaningful.
Great comment!
Cheers
Sarah
Perfect timing! I’ve recently been reassigned to a new project and this one is developer content — APIs, SDKs, prodkits, and it’s wiki-based. Thanks for the links!
Hallo Patty
I’m so glad they’re useful, and I hope you have lots of fun in your new project!
Cheers,
Sarah
plz brief me about technical writer i want to be technical writer as job
FIrst of all, learn English.
Great article. I specialise in user help technical communications rather than api development so interesting to see your approach here.
Hallo George
I’m glad you enjoyed it. My previous role was a combination of user help and API documentation. Another interesting area is documenting developer products. This is similar to user documentation, in that you’re often describing a user interface. But the audience is the same as for API docs.
Cheers
Sarah
Hi Sarah,
I love to write and I love working with code, so I’m trying to launch a career as a technical writer for developers.
I’m curious about how you got into writing for developers. Were you already in a technical writing role and got a project on documenting code? Or did you actively seek out technical writing jobs that required the ability to understand and write source code?
Hallo Carmela
I started out as a developer, then moved into technical writing. At first, my roles focused on user guides and admin guides, but then I started looking for tasks on the developer side of things. I love the developer relations role, where the aim is to help external developers use our APIs, libraries and development kits. Its great that you’re looking into this type of writing too!
Cheers
Sarah
Sarah; Did you ever prepare and present a presentation on this topic? If so, I’d like to see it.
Hallo quipquopro
This presentation covers the basics of the role, and includes some tips on getting started:
Cheers
Sarah
Hi Sarah
I have no dogmatic objections but fully agree with your fantastic summary.
The attitude is quite important, and I am adding something to this thread. Based on the TW/TC consulting situation in my workplace there are some findings from my side that may help people like me.
• TWs shall always leading the tasks, either transactional or transformational, instead of waiting for input, we shall actively drive the document development.
• Using communication skills or different reference powers to help the API SMEs to support documentation team.
• Take initiatives and bring suggestions for issues.
Thanks again for your great post.
Brs//Jibing
Hallo Jibing
That’s a great comment. Tech writers do need to act as leaders and take the initiative. This applies to the documentation itself, but also to aspects of the product itself and the team procedures. Often, the tech writers in the team have plenty of experience of software development as well as a broad view of the product suite. We’re in a good position to lead.
Cheers
Sarah
Pingback: APIs Technical Writers – Technology For Writers
Pingback: 2016 Technical Writing Trends and Predictions, or the Ripple Effects of API Growth on Technical Writers – Intercom