What You Need to Develop Great API Documentation
API documentation is highly-demanded on the tech comm market today. And, judging by how many services and products now rely on this technology, the demand is not going to decline any time soon.
Today, let’s talk about what you need to become an author of high-quality API user manuals.
Learn About Programming
Having an IT or CS background is a great shortcut for somebody who wants to start creating API documentation. For instance, if you have experience in developing GUI-based software documentation, this can be a smooth transition for you.
API docs are more focused on developers. Devs being the primary audience makes the ability to speak the same language with them crucial. So, familiarity with programming languages is often mentioned as a prerequisite for landing a role of an API tech writer.
Learn About API Technology
Of course, understanding what API is and how it functions will be a huge advantage when trying to get employed. There’s no shortage of information available online in the form of articles, guides, and online courses.
Here’s an exhaustive guide designed specifically for technical writers to learn about APIs and documenting them — https://idratherbewriting.com/learnapidoc/. This is a great resource covering a lot of important topics. I already mentioned it on my blog, but this is one of the best courses out there, kudos to its creator, Tom Johnson.
Get Fitting Technical Writing Software
Now, you can write documentation using Microsoft Word (and, some writers, sadly, still do), but to produce a product of higher quality you will require professional tools tailored for this.
Look for a help authoring tool that supports creation of API documentation. Some features you might be looking for in a HAT:
- Code highlighting. API documentation contains a lot of code and without this feature, it would be so hard to read.
- Separating code from text. Highlighting is great, but to make code samples stand out even more, look for a solution that allows adding code samples to dedicated blocks within a help topic.
- Security. Your API documentation might contain sensitive data. I would look into this aspect when choosing software for sure. What servers do they use to store data? Can you use your own server? What about SSO? Can you set up roles with restricted permission? These are just some of the questions to consider.
- Teamwork options. You will need to collaborate with many people to create API docs: be that SME’s, devs, QA engineers, or fellow tech writers. Such user manuals are a collaborative effort. Pay close attention to what teamwork features are being offered by a HAT’s vendor.
Create Portfolio
To prove you are a worthy asset, real samples of your work would be handy. You might already have an extensive portfolio, but, since we are talking about a very specific field, we need to laser-target it.
Your potential employers will be mostly interested in developer-oriented documentation samples. So, take your time to sort it out. If you need to create more samples, allocate time for that — nothing speaks louder about your expertise than well-written help topics in your portfolio.
Conclusion
If you are looking for an IT-related tech comm career, I would certainly recommend looking into creating API documentation. This field definitely has potential and it opens doors to many prospering IT companies.
