SearchCtrl K



Developer Relations: Devoting time to housecleaning

August 16, 2021 - Doug in devrel

Every now and again I'll read a tweet about wanting to get into developer relations: You'll get to travel the world to attend conferences, write cool blog posts and build applications.

..and they are not wrong. Creating content and embracing your community is a huge part of developer relations. At api.video, we spend a lot of time brainstorming and creating content. We also work to attend conferences (most of which are remote at the moment.)

Many developer relations KPIs include things like "the number of blog posts written", or "how many demos have been published this quarter"? "Have the tweets gotten good engagement"? "Is traffic increasing to the website"? "Are registered users going up?" And these metrics all have their place (some are better than others, but that's probably best saved for another article).

In this post (and in coming posts), we're going to discuss additional aspects of a good devrel program that are often overlooked (and that are even harder to quantify): Housekeeping, technical debt and other bits of work that do not have the same "glory" as speaking or building demos, but are an essential part of any developer program.

In this post, I'd like to address housekeeping. If you have the most beautiful home, but don't regularly dust or clean, you'll soon be inundated with dust bunnies, dishes overflowing in the sink, etc. Your once beautiful home will not have the same sparkle. So you set aside time daily and weekly to make sure you house is being kept clean: perhaps one room at a time, or one area - just to keep the house looking good, and running smoothly.

A developer program is no different to your home. I mean - are the docs ever really done? Can your tutorials be cleaned up? Were there any changes that require updates? Does one question keep resurfacing? Should it be a FAQ? Should we add another link in the docs to help clarify?

Just like in your home, your developer program should have regularly scheduled housecleaning to make sure that the docs and the tutorials are ship shape.

Keeping the docs fresh

Have you ever read the docs of a new product you want to try and found pages that contradict each other? And you don't even know where to start, because the docs cannot even agree?

At api.video, our team is in hyper growth mode. Not only is the team growing like crazy, but the products are constantly evolving, and new features and tools are regularly being released. Whenever we release a new feature, we make an announcement (of course!), but we also do an audit of our existing docs.

The audit

When a new feature releases, it's possible that a previous tutorial or document is now out of date. So, when a new feature is released, we do an audit of previous posts and tools to make sure that those documents are updated as needed.

For example, we recently released a new Javascript Uploader library to make it easier for web developers to integrate video upload. With just a few lines of code, you can be up and running.

But: Before this library was launched, we had released tutorials on how to code a video uploader in JavaScript. We'd built demos upload.a.video(https://upload.a.video], upload.a.video/toDiscord, and written many tutorials on how to upload a video with JavaScript. There's nothing wrong with these demos, or with the code behind them - but there's an easier way now.

So after launching the blog post New Video Uploader JavaScript Library, and our new demo upload.a.video/JS.html, we went back to our existing posts that feature the older code snippets, and added an update pointing to the new "better" way:

(also note an update in Feb 2021 to fix a bug with naming.)

When we decided to deprecate our SDKs for a set of API clients (improving the speed of updates to the API clients, and easier, less buggy development on our end), we marked each SDK repo/document and reference to the SDK clients as being deprecated, and how to do the same work with the new API clients.

The update

We're constantly updating and refining our API documentation. I don't know if there is any documentation that can ever be called complete, but we make regular passes at what is there to make iterative improvements on what we have.

If you look at the 3 most recent pull requests to our API specification, we recently added live webhooks (a new feature), but each PR to the repository also improved formatting, linking and layout.

Documentation trick: have you ever seen docs that are awesome at the top, but the quality slowly degrades as you make your way through the API endpoints? If you always begin updating top to bottom, you'll get "update fatigue" and the dip in quality shows. Next time, start updating the docs from the bottomm-ost endpoint and work upwards!

We make the changes in the documentation based on our reviews of the questions we get from developers.

"We've had 3 developers who contacted us recently, and did not know about feature x"

If we hear from our support team that many developers are asking about a feature, we edit the docs to more clearly describe the feature, add links to tutorials and more detailed descriptions, so that the next developer does not miss that we have the feature x that they need.

Documentation trick: have you ever seen docs that are awesome at the top, but the quality slowly degrades as you make your way through the API endpoints? If you always begin updating top to bottom, you'll get "update fatigue" and the dip in quality shows. Next time, start updating the docs from the bottom-most endpoint and work upwards!

The upgrade

Like many APIs, we use external tooling to display our documentation. In our case, we use ReadMe. Last week, we received an email about their new updates on how they will display our API. This update looks like a 'no-brainer' - the new layout is a big improvement and will make our documentation more readable. But, as we read the release notes more carefully (yeah, that is how we roll), we realized that the URL structure for each API endpoint will change upon pushing this update.

This is no longer a simple update: we'll have to comb through all our blog posts and documentation to make sure that the links to the docs all work, and are pointing exactly where we want them to go. I'm a big fan of linking into the docs to show how each API is being used, so there are a lot of links in the docs. On our last update similar to this, there were > 30 blog posts to update - so undoubtedly, this update will have even more blog posts to update.


While a big part of our role in developer relations is creating awesome docs and fun tutorials, that's only a small part of the work. Keeping all of the docs in order - so that developers can quickly find what they need, and keeping everything up to date is also a major task of the devrel team, and as more and more cool docs and tutorials are created, the housekeeping work increases as well.


Head of Developer Relations

Recommended Articles

Connect your users with videos

Create a free account today