The best way to ruin your reputation in the dev community is by keeping lousy API documentation. For the developer who just spent half a day trying to integrate your payments solution into their platform, an outdated doc isn't just annoying, it's a massive waste of time.
Your docs are a window into your product. Documents that detail deprecated features or neglect to mention important updates will be seen as red flags that your code isn't up to snuff. If you can't tie up loose ends with your API, what other oversights have you allowed for in your software?
But too often documentation falls through the cracks because of poor communication. Who updates the docs and when is decided on an ad-hoc basis with no real agreement about standards or best practices.
In order to keep clean, updated docs, you need to establish a culture of communication surrounding your API. Here's how.
Set Standards for Your Docs
Every developer has their own way of doing things. Without a common standard for what's acceptable, some parts of your docs will end up crystal clear, others haphazardly slapped together, and others completely neglected.
That's why Facebook's API has earned itself such a bad reputation. One developer on What the Daily griped:
Facebook doesn't have a consistent process for keeping API docs up to date. To make things worse, they do a terrible job of communicating API changes to developers. Each time Facebook releases an update, developers are left scrambling, having to dig through Facebook's documents, blogs, and support pages to find answers to simple questions. Avoid this debacle by writing down standards for how your documents should be kept.
Write it Down
Documentation for how to write documentation sounds like bureaucratic nonsense, but it works. And we're not talking manuals, we're talking a clarification of standards. Every developer holds documentation to a different quality standard, so it's vital that everyone gets on the same page.
Note your high standards from the get-go—whether that's in an employee handbookor your internal procedure documentation. Here are some things you should be sure to include:
- See-it, fix-it policy. The more eyes you can get on your documentation the better. Let everyone have access to your documentation page, so that you have the best shot at fixing every tiny mistake.
- Schedule for updating. More on this below, but make sure you regularly scan for errors and make updates based on user feedback.
- Formatting guide. While a switching up of colons and en-dashes will only the bother the anal-retentive among us, mixing up H2 and H3 headers or how we format warnings can be misleading.
If you don't set explicit expectations, your documents will start to slip and no one will notice until the dev forums flare up with complaints. Documenting is a way of carving procedure into stone and immortalizing what's important. This will trickle down and affect the priorities and values of your team.
Hold Everyone Responsible
Documentation should always be a collaborative process. You're trying to appeal to a huge range of developers, so the more input you can get, the better. No one loves documentation—except us, of course— so alleviate the burden from any one single person, and involve every developer on the team.
But a huge collaborative project always runs the risk of becoming a free-for-all. People will only fix what they want to fix, not what needs to be fixed. You'll end up with documentation that looks like this:
The nod to open-source underlines a strong point. When a project doesn't belong to anyone, everyone contributes as they please, neglecting the tedious but important work. That's why open source projects often have terrible documentation—despite the importance of updating docs, it's a job that no one wants.
Have a point person
While everyone should do their part in updating docs, every project still needs a point person. This is the person who's responsible for making sure that documentation gets updated—not necessarily the person who does the writing. Your point person can be:
- The person in charge of the feature or update. The developer that actually worked on the project knows best which parts of the documentation the update would affect.
- The head engineer. This person already has some managerial experience, so they will feel comfortable delegating the task of writing up or editing some documentation.
- Decided on a rotating basis. If your team is small this is a great way for everyone to feel ownership over the documentation.
Most dev teams update docs according to their release schedule. So if you release bi-monthly, you can update docs a few days before each. Build this into your release process, so that documentation becomes a force of habit.
Handle A Tech Writer With Care
In the early days, most dev teams don't need a technical writer. We created ReadMe so that developers wouldn't need to commit too much time or too many resources to sharing their API with the world. But as your platform starts growing and gets into the hands of more and more users, your developers might no longer have time for docs. That's why most bigger tech companies like Atlassian end up hiring a full-time tech writer.
If your situation begins to call for a tech writer, tread carefully. You don't want to create a chasm between what's built and what's communicated. If you just hand over the reigns and let the writer have at it, you'll end up getting reactions like this:
With a tech writer, make sure that the documentation is still a collaborative effort and the developers who actually worked on the product have input. A tech writer might have the writing and the technical chops, but they don't know the product well enough to decipher what features are most important, or what information should be prioritized.
Treat Them as a Part of Your Dev Team
A tech writer can either be the secret weapon or the downfall of your documentation. If they don't work closely enough with the dev team, you'll end up with documentation that's similar to what an autodoc tool can spit out— full of definitions, without much guidance through the learning curve of your API design.
The trick is to onboard your tech writer as a part of your dev team. Have them work closely with the engineers to learn about the product, the audience, and the quality standards. They should be:
- Attending daily stand-ups. It'll not only keep the tech writer informed about upcoming projects, but it will get the developers a part of the documentation process faster.
- Discussing every product update with an engineer. Incorporate a thorough briefing into the deployment schedule. The engineer should offer an overview and explain all edge-cases to the tech writer so that they can provide context for the reader in the documentation.
- Looking for user feedback. The best QAers of the documentation will be the API users. Create a hub for your documentation where users can ask questions and point out mistakes. Then, have your tech writer regularly check in and eliminate any inaccuracies.
Every company handles tech writers differently, but it's crucial for there not to be a disconnect between the people that build the product and the people that communicate it.
Make Updating Docs a No-Brainer
Remembering to update docs is hard. Between working through different stages in the agile process, gathering feedback, and fixing bugs, documentation is the last thing on the minds of your dev team. That's why the only way to make sure they are updated regularly is to build it into your deployment process, and delegate ownership over the project. This way, nothing will slip through the cracks again and your API will be more accessible than ever before.
