The tech-writer’s journal #8— API Changelogs
Welcome to yet another post on the Tech Writers’ Journal. In this blog, we will discuss changelogs in the API documentation.
Recently, I had to do research on changelogs, their creation, and maintenance. This post entails the conclusions I’ve drawn, and the intent is to help other tech writers out there who want to create a changelogs for their APIs.
Without much further adieu, let us jump right in.
What are changelogs?
Although there is no official definition for a changelog, it is simply a bullet list of all the notable changes (in reverse chronological order) made to an API.
Why have a changelog?
A changelog acts as a bridge between the current version of your API and its previous versions. It has varied impacts on people with different roles. For a developer, a changelog reflects the speed of development. For a customer, it builds credibility and confidence in a product, and so on.
How to structure a changelog?
A changelog must always be in reverse chronological order — the most recent change comes first. While there are many ways to structure a changelog, here is a generic format.
By structuring your changelog this way, you make it easier for the user to skim through the changelog and absorb the content effortlessly. Also, ensure that you make changes with code breakage painfully clear. You can add them as a warning text, make them bold, or anything to make sure that your developers do not miss it.
Should you add code samples to your changelog?
In general, a changelog does not have a detailed explanation of changes made. The ideal place to add code samples and other details would be official documentation, release notes, newsletters, or blog posts. However, given that there is no hard and fast rule on what goes into a changelog and what does not, it is up to you to decide.
What are some red flags that you must try and avoid?
Here are some tips and tricks to iron out wrinkles in your API changelogs.
- Keep a keen eye on what goes into the changelog. Present only the information that is relevant to your developers.
- Do not ignore deprecations, especially if they lead to code breakage.
- Present the dates in ISO format. This way, time and date information is standardized, resulting in fewer communication issues.
References
Here are some of my personal favorites:
