Advent of Technical Writing: Deprecating Content

This is the tenth post in the Advent of Technical Writing series, wherein I will share something I have learned from my experience as a technical writer. My experience is primarily in software technical writing, but what you read may apply to different fields, too. View all posts in the series.

Taylor Swift's lyric "'Cause we never go out of style" doesn't apply to documentation. Documentation needs to change, often. When a new API, product, or feature deprecates an old one, you need to make sure your documentation remains up-to-date and encourages best practices. You don't want your documentation go out of date. (Notice the callback to the Taylor Swift lyric.)

Communicating with the team about deprecations

Deprecations rarely come without notice. As a technical writer, you should stay close to the teams whose work you are documenting. Listen out for any code, SDK, or product changes that may require action. When you hear that a tool may be deprecated, start communicating. Gather information on:

1. What is being deprecated;
2. When it is being deprecated;
3. Why it is being deprecated;
4. The extent to which the old software / API will be supported, and;
5. Any transition plan that other stakeholders (i.e. product or engineering) have in mind.

At work, we are presently deprecating a video stream interface for one of our open source products, Inference. This work had been going on in the background; it was on my mind. Then, as we got closer to release, an engineer wrote documentation on the new interface. I started to mentally collect answers to the above questions. Let me answer the questions above, in order:

1. An API, called inference.Stream() was being deprecated.
2. We were announcing it in our upcoming release in a few weeks.
3. It is being deprecated because we have made a new version that is significantly faster (as evaluated by benchmarks) and includes helper functions that reduce the amount of code our customers need to write.
4. The old API will remain supported. But, we will encourage all users to use the new one.
5. We have no specific date in mind for the feature to be officially dropped, but when that date comes we will give sufficient notice to users and update our documentation as necessary.

Having this information was immensely valuable. I could start to think where we had documented the feature, the urgency with which I would need to update content external to the main documentation (i.e. tutorials and blog posts), and keep in mind the new API as I wrote new content. I could also make sure I recommend it to our field engineering and sales teams if I get questions. I could think about promotion.

The deprecation lifecycle

Content deprecations start with an announcement that a product, SDK, or API is being replaced with a newer version, or will no longer be supported. You will likely need to produce content on both the new product or API being introduced and work with your team to put together a deprecation plan for content that is about to go out of date. The deprecation (i.e. setting timelines, removing code from a codebase) will be managed by product, but you will be responsible for the communication work in terms of updating content and writing new content where relevant.

When you start planning a deprecation, take notes on:

1. All of the places where content will need to be updated;
2. Site pages that you may want to deprecate;
3. What new content you will need (product pages, blog posts) to ensure a new feature is well documented, and;
4. The order of priority in which changes and new content needs to be made.

When it comes to new product or open source changes, my first priority is the product or code documentation. Since the main product or open source project documentation is the canonical source of documentation for a respective project, it is important that the requisite updates are made there, first. Then, I work my way through other places that need to be updated (i.e. blog posts).

Once you have made the requisite updates, you need to communicate them to your team. Make sure everyone knows about your new documentation so they know to refer to it. This is particularly important for significant changes that may effect the architecture of a site (i.e. major API releases that are available on a different subpath).

Below, I am going to talk in more detail about deprecating APIs and content (i.e. blog posts). I am not going to talk about deprecating full pages of product documentation since I have less experience with doing so.

Deprecating APIs

When you deprecate an API -- whether it be a REST endpoint, an SDK function, a CLI command, or something else -- it is important to have a plan in place. When you deprecate an API, you will have two pieces of content to think about: the documentation for the old API and the new one. This documentation may be on the same page or across different pages.

Your old documentation should include callout boxes that informs users of the deprecation. You should state the official date after which an API will no longer be supported with as much advance notice as possible.

Your new API should be prominently located in your documentation when a user is looking for the feature. For example, we are updating our quickstart guides to use the new Inference streaming interface. We will ensure the new one is high up in our Run inference on a video guide, which is the canonical source of information about the API. We will include a note about the old API being deprecated. We will keep our content on the old one for users who need it, but that content will be in a tab or toward the bottom of the page.

For more complex projects such as introducing entirely new APIs (i.e. a GraphQL API), you may opt to use documentation versioning. This involves having separate sections of your site (i.e. v1, v2) fo reach API.

Ensure planned deprecations are announced in advance in release notes and change logs, and when an API is officially deprecated or unsupported.

Deprecating content

In addition to deprecating APIs, you may need to deprecate content if the underlying product or API on which it depends has significantly changes. This could involve updating help center articles, blog posts, product guides, or other materials that you have written.

For example, Roboflow released a new Video Inference API, which enables you to run inference on videos in bulk faster and cheaper than using our image API, which was designed for images. The team wrote a guide two years ago on how to use video inference with our old API, which is now out of date. We wrote a new guide on how to use our new API since the methods are fundamentally different. We will redirect our old guide to the new one so that users can easily find it.

It is important to make sure changes are made across all sites you own when you deprecate content, not exclusively in the documentation most directly related to your product. For example, our old video inference blog post was not in our product documentation. But, it ranks in the top spot on Google for roboflow video inference. If people search for this product in Google -- a likely user journey -- they would see old information.

If you think a piece of content is no longer relevant, you may:

• Unpublish the old content and redirect to a new page with up-to-date content, or;
• Update the old page with a clear disclaimer notifying the user that the content is deprecated.

In cases where you have a new product or guide that a reader can follow, unpublishing the old content and redirecting to a new page is the best experience for the reader. This approach eliminates the need for a reader to make a decision to navigate elsewhere themselves to find a solution to their problem. If you are deprecating a feature and dropping support, the latter option -- adding a disclaimer to the page that the content is deprecated -- is ideal. In that case, you should still refer to other helpful resources that may assist the reader in finding the knowledge for which they are looking.

Conclusion

Good documentation is accurate, up-to-date, and provides the reader all the information they need to learn about a subject or accomplish a goal. Documentation is not static, however. As a technical writer, you will create content, design navigation structures, redesign navigation structures, update existing content, and deprecate old content.

When you hear that an API or product is going to be deprecated, make a plan with the relevant engineers and product managers. Ensure readers of your documentation have sufficient notice, where "sufficient" is determined by your team.

For big changes, like an entirely new API version, you may launch the new API version and maintain support for the old one for a few years. For small changes to an SDK, you may officially drop support for a function or a method after less time. Whatever the case, make sure readers know what deprecations might affect them. Update documentation as appropriate. Redirect old documentation to your new documentation.