Advent of Technical Writing: Feature Releases

This is a ✨ bonus ✨ 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.

One category of content I write is a feature release. This is a blog post that announces a new feature. This feature might be an addition to an existing product, a new product, or a feature available in open source software. From a technical marketing perspective, feature releases provide significant value to you, your team and customers.

In writing, you will become an expert on the feature and may come up with ideas that could be used to improve the product. You will push your team to have answers to key questions, like for whom is a feature available, which will help the team become aligned on a new release. Customers will benefit from comprehensive, cohesive knowledge that acts as both an announcement and an introduction to a new product.

When I am writing a feature release, I aim to answer the following questions:

• What is the feature?
• Who would use the feature?
• For whom is the feature available?
• How can the reader use the feature?

What is the feature?

Defining a feature is an essential part of a feature release. Let's look at how I announced Video Inference, a new product release from Roboflow. The blog post covers the product itself (the video inference infrastructure) and the means by which someone uses it (the SDK).

I introduced the product like so:

We are excited to introduce the Roboflow Video Inference API, which allows you to apply computer vision models to videos in the cloud. With the video inference API, you can use the video infrastructure we've relied upon internally, which handles things like batching requests, concurrent processing, and complexity associated with scaling with inference on the frames in a video.

How you introduce a product is very much a marketing question, but refines a muscle you will use all across your technical writing: explaining concepts with clarity, adjusted for the audience.

Above, I say what the feature is and what it allows the user to accomplish. This information is included in the introdcution, after some contextual information that helps guide the reader in the guide.

Who should use the feature?

Product and open source releases are rarely relevant for everyone in your audience. You should clearly state who would benefit from using a feature. You can do this both by stating key features and by providing use cases.

By stating features, readers can evaluate the product or code. For example, I noted:

The Video Inference API is designed to scale with any use case, whether you are working with a small collection of videos, an archive of years of material, or videos that come in every day. Use secure signed-URL endpoints to upload videos from S3, GCS, or Azure Blob Storage with confidence. All this makes adding video inference a secure and frictionless experience.

To the audience I had in mind -- people who want to use computer vision models on videos -- this is important information. Knowing that the solution scales and works with cloud storage providers is key context that speaks to how the tool might fit in your workflow.

Let's talk about use cases. Another way to think of a use case is an issue for which your product or code solves. In my video inference guide, I made a list of a few use cases:

1. Generate tags for use in building media search engines;
2. Analyze videos for brand and safety requirements;
3. Run security footage to detect objects of interest;
4. ...

This list of use cases explicitly outlines some of the many ways in which the tool could be used.

For whom is the feature available?

State for whom your software is available, especially if there are limits on who can use the software. Does someone have to opt in to a beta in your product? Is the software available only for paying customers? Is the software generally available?

You should state if any of these cases are true with the requisite context. For example, if a feature is in beta, you may want to set expectations of reliability. If a feature is only available for paying customers, you may want to include how someone can use the feature (i.e. reach out to their account manager).

How can the reader use the feature?

Once you have announced the feature, you should show how to use it. This is your time to walk through an end to end example of the software or code in action. In the aforementioned video inference guide, I showed how to use the feature in a way that is intuitive. The reader can start with a video and end with predictions visualized on a video. The guide could have ended by showing the JSON results from the API, but showing how to plot predictions will help improve comprehension over what the API can help you achieve.

Conclusion

The advice above applies no matter if you are writing a product announcement, an SDK extension, a new feature available in open source software, and more. By answering the four questions above, you can ensure that your readers have the information they need to:

1. Know what a feature is
2. Evaluate if the eature may be useful to them
3. Experiment with the feature

Of note, a product announcement should not be the same as your product documentation. Whereas you can walk through an example use case in a product announcement, product documentation should be use case agnostic and document all of the edge cases and usage situations.

The aforementioned video inference guide walks through an example of sunning an object detection model on a video. But, the tutorial notes other models are supported, such as foundation models like CLIP. How to use other models is explained in the full product documentation, which is linked on the page. A product release should not be the canonical reference material for a feature, rather an introduction to that feature.

That's it for today's technical writing tip! Join me tomorrow for another tip.