Question: Which software tools should I use if my goal is to write API docs?
A reader asks:
I’m an aspiring technical writer and I’m taking courses for a Masters in Tech Comm. What software tools do you think a freelance writer should own to be successful. Should I own MadCap and Framemaker? My goal is to write API docs for developers.
Great question. Finding the right authoring tools for developer documentation, specifically documenting APIs, is a topic I touch upon briefly in my API course. The short answer is that there are many different tools for creating documentation, and there’s no clear industry standard in this space. You’d be better off devoting time to deepening your technical background with programming languages and technical concepts rather than focusing on doc tools.
Different tools may better suit different environments, skill sets, and products. Currently I’m using Jekyll and have been for several years. At my work, we recently completed an engineering integration where we build and deploy Jekyll’s web output directly from the server. This is the docs-as-code tooling approach.
This workflow fits our authoring needs quite well because we’re in a large engineering group with a lot of engineers who contribute documentation. Most engineers like to write in Markdown, and they are comfortable interacting with text files in repos. For example, we may send an engineer a review task, and he or she will respond by submitting a change request (using the same Review Board tools as with code) to merge his or her edits into a branch in our doc repo.
Because we are only a small handful of authors responsible for hundreds of pages of documentation across a wide swath of deeply technical topics, we know we need to rely on engineering contributions and involvement to be successful. Therefore we selected our tooling to fit our needs and environment.
We’re also not generating a full website with Jekyll, but are instead inserting the generated HTML into a larger website (with a robust header, footer, search index, and localization logic). (You can browse our documentation here.)
If you want to pursue the docs-as-code route, you could use a number of tools besides Jekyll. Sphinx, Hugo, Middleman, Slate, and Mkdocs are just a few static site generator options.
In this same category of static-site-generator tools, there are also many hosted options for developer docs. Readthedocs.com, Forestry.io, CloudCannon are all excellent choices. Also check out Readme.com. If your company allows you to use third-party hosting for your content and you have budget, I’d recommend this route instead of trying to build your own theme.
If you’re documenting REST APIs, definitely check out the OpenAPI specification and SwaggerHub. Find a doc tool that supports the OpenAPI specification.
If you have more robust requirements around translation and content re-use, you might want to use a more traditional help authoring tool that excels in this area. Both Madcap Software’s Flare and Adobe’s Tech Comm Suite are widely used tools in the tech comm industry because they handle just about every tech comm scenario you will encounter. If you’re trying to ramp up your tech comm skill set to look attractive to employers, familiarity with these tools will make you better qualified for a broader number of jobs.
There are also some hosted doc services for tech comm tools if you need to collaborate online. Paligo and Corilla are two new doc platforms with a lot of momentum.
(Note that a lot of these companies advertise on my site — see my sidebar for a list of current advertisers.)
However, to break into developer documentation (which is what I presume is your larger goal), employers are often more interested in your programming background/knowledge rather than specific documentation tools. Tools are seen as a means to get a job done, and companies want you to spend as little time on doc tooling as possible so you can focus on content.
Learning how to document code written in Java, JavaScript, C++, PHP, or some other language or platform (iOS, Android), can be more difficult and require more preparation than learning a doc tool. Companies will typically look primarily at your technical background, and then secondarily at any doc tools you’re familiar with.
Additionally, unless you’re revamping the doc tool set at a company, many times there is already adequate tooling in place. It could be Confluence, Google Docs, or even Microsoft Word. The company is likely hiring you to fill a documentation need, not to implement a new documentation toolset. Therefore your best approach for success in breaking into developer/API documentation is to deepen your technical learning and preparation, and not to get too mired with doc tools.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.