There are many types of technical writers, such as an automotive technical writer, a technical writing manager, etc. This blog will explain what an API technical writer’s job is about.
What Is an API?
API stands for Application Programming Interface. It means a code that allows two different apps to work together. For instance, look at the following scheme:
To explain it better, let’s take an example of an API we frequently use. So, if you want to join Medium (an online publishing platform), you face the ways of signing up. You have three of them: using Google, Facebook, and email.
If you want to save time, you will choose Google or Facebook. In this case, an API allows Medium and social networks to connect and check if a user is ready to log into the system in such a way. Then, an API requests confirmation from the user.
That’s how APIs work.
API Technical Writer Responsibilities
API technical writers help developers to understand how to use a particular API. The first ones create special documentation for this purpose, but before such a step, they spend a lot of time researching and analyzing initial data. When this preliminary work is finished, API writers usually start to describe use cases and API features.
Let’s take Vimeo (a video hosting platform) to demonstrate a great example of API documentation; that will help better understand what API writers do.
The section for developers starts with the basics of using Vimeo’s API. Such a guide is great because of the following features:
- It has script examples — they are shown in specific dark blocks. It’s easy to copy these code pieces and use them.
- The author of this document explains complex terms in blue blocks for newbies; not every reader understands all specifications.
- The author clearly describes the next steps at the bottom of the page; it’s great that a reader can watch video tutorials about API features.
In other words, to create helpful documentation, API technical writers gradually describe essential features by taking code examples and explaining specific terms to beginners.
API Technical Writer Skills
Maybe, you are convinced that being an API writer is not an easy path. There are core skills every API technical writer should have:
Communication skills. It’s crucial for API technical writers to interact with people correctly. First, API writers explain complicated things to other professionals; if the former can’t use appropriate words to describe some problematic concepts, nobody will understand their documentation. Second, API writers can conduct interviews with developers to know some critical moments before creating docs. The first ones should be able to ask the right questions to get as much helpful information as possible.
Knowledge of API documentation tools and programming. This point shows the main difference between API and other technical writers. API writers can work on products that need knowing the following languages: JSON, Java, Python, JavaScript, and C++. As seen from the above section, API documentation can include special blocks with code examples. Regarding professional tools, API writers should be aware of help documentation software such as Swagger and ReDoc, for instance. These free tools make data more readable and help users automate routine tasks. If you need a professional technical writing tool, have a look at ClickHelp.
Writing and content editing skills. API technical writers should avoid grammar mistakes in their documents; such errors have a negative impact on a company’s reputation. Besides, it’s vital to structure API documentation to make it easier for people to understand product features. For example, if all documents consist of endless paragraphs without any visuals separating these pieces of a text, readers will spend a lot of time trying to figure out the material. Sometimes, it’s critical to use not only text and illustrations but video tutorials as well.
API Technical Writing Salary
According to Talent (the board for finding a job), the salaries of API technical writers in the USA range from $89,563 to $128,400, with an average salary of $111,760. Let’s compare such data with another source. Glassdoor job review platform shows that API technical writers in the USA earn on average $85,128 and get $17,101 as additional pay, which includes bonuses or profit sharings, for instance.
API Technical Writer Job Description
If you want a job description, you should find an appropriate vacancy on the Internet. There are approximate job requirements for an API technical writer.
Minimum Qualifications:
- Excellence in writing English. You should write clearly to explain complicated issues to the intended audience.
- More than two years of experience with RESTful APIs, code review tools, and simply code repositories.
- Experience in creating technical documentation (SDK documents, API references, and product guides).
- Compliance with deadlines.
- Experience in dealing with developers, project managers, and UX designers to create clear product documentation and describe essential features.
- Experience in writing HTML and Markdown from scratch.
- Understanding CMS software — Contentful, Umbraco, or dotCMS.
Preferred Qualifications:
- Being a pro at Git.
- SCRUM or Agile Experience.
- More than four years of experience with KM tools.
- Deal with company managers, clients, and vendors, to write technical specs and determine the subject material to be created.
- Knowledge transfer and training experience.
- Develop high-quality documentation templates that allow you to work with single-sourcing and content reuse features.
- Understanding coding best practices in Python, C++, and JavaScript.
- Analyze documentation to define the necessity for making changes in previously published files and creating new docs.
- Maintain material, files of work, and edits for future use in the CMS.
- Edit documents API code authors and developers have created.
There are primary requirements for an API technical writer, but a final description depends on the needs of a company. Sometimes one needs a Bachelor’s degree in a related field — technical communication, for example.
Conclusion
Becoming an API technical writer from scratch is challenging; you should be proficient in programming and writing. It’s easier to start this career if you have experience in development, for instance. Nevertheless, permanent practice will help you achieve such a worthwhile goal.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices
