Companies need to understand that API documentation is its own specialty, no less than medical writing or marketing communications. Almost every aspect includes reading and writing code to make life easier for your developers consuming your API. Yet many companies still make basic mistakes.
“…most of my clients think about documentation too late and resist paying respectable rates when they find the rare combination of developer skills and technical writing talent.” – Andrew Davis, founder of SynergisTech.
Table of Contents
So, Who Owns It?
The conventional thinking is it should be a developer that helped build the API. Who has a better understanding than them, right? True, but most developers are famously bad writers (sorry folks) and would rather be writing code. Technical writers seem logical, but they often aren’t developers. As a result, the job of creating API documentation gets passed around, neglected and no one really knows who’s responsible for making sure it gets done, and done right.
To start finding the right person, whether that means looking internally or hiring outside your company, ask yourself:
- Do they have a solid understanding of software development? They don’t have to be rock star, but they need to know the basics. A good test is, can they code to the API they will be documenting?
- Can they can simply explain a complex idea and help the reader understand new concepts? Blog posts, technical documentation, internal presentations, where have they done this before? If you believe Occam’s Razor applies to software (we do), then it also applies to API documentation.
- Will they explicitly know they are responsible for the completion and quality of the API documentation? (obvious I know, but so many companies neglect this)
What’s the Scope?
With these skills, they can start crafting your developer experience. Think of it like a roadmap, detailing the actions a developer must take, along with supporting information like tutorials, use cases and code samples to build a new application using your API. The right person with development experience can create their own code samples to provide context for your API and help bring concepts together. Developers may already know what API call they want to make and it’s just a matter of showing them how it can be set up. They can also reuse code samples and modify them to fit their needs. Skilled team members can even provide additional resources, tools, sample applications and notes all within an SDK, reducing the time to the first “hello world” for your API developers.
Automated Tools Are Good, But…
These tools generate API documentation directly from the source code, listing items like parameters and name spaces. They’re very good at creating stylized and accurate documentation and should be used as part of the process. However companies often rely solely on these tools and that’s a mistake. It’s a case of providing 100% coverage and still being incomplete, because they lack descriptions, explanations, and samples. Even the most popular tools, like Swagger and Doxygen overlook additional documentation. Swagger will easily create the parameter list (such as JSON input and output members), but it doesn’t describe their meanings or how to set up the call. You still need the right person on your team to bridge that gap for developers.
So, What’s The Role?
What do we call the person that has the rights skills and is responsible for the quality and completion of your API documentation? API writer, programming writer, developer? The best API documentation is going to come from companies and people that can balance technical writing, editorial and the ability to write code. Finding that balance is hard, but done is always better than perfect, so pick the best person you can find and let them own it.