The tech-writer’s journal #11 — Using videos & screencasts in developer documentation
In a recent survey conducted by Tom Johnson on the trends in technical documentation, only 27.79% of the technical writers had chosen that they create video tutorials and screencasts. 56.82% of them have stated that they do not, and 13.65% of the writers have stated that they are planning to create them soon.
This blog post is for technical writers and explains concepts in the context of developer documentation, REST APIs, to be specific, GUI documentation, and developer relations. It assumes that you are familiar with the basics of technical documentation.
Why add videos to developer documentation?
In today’s world, there are tens and thousands of public APIs available. Many statistics also state that the number of developers who consume the APIs is also increasing day by day. So let us take a step back and think of the pool of developers who might be consuming them. These are developers with different backgrounds, different learning styles, different mental and physical needs. It is essential to create products that cater to the needs of all your users.
Significance of developer documentation
It is through documentation that developers understand your product/tool. It is not only the initial bridge through which they familiarise themselves with the product, but also they return to it when they face any difficulty in the process of using your API. It is crucial to create products in a way that it caters to the learning needs of all your developers. There are four learning styles — visual, auditory, reading/writing, and kinesthetic. Shockingly enough, most of the developer documentation that is out there is predominantly text.
When you ensure that you cater to the different learning styles in your technical documentation, it becomes easier to grasp information, learn and understand your product better. Once your users understand your product better, it ultimately reduces pressure on your support team.
Videos in GUI docs
While it is rare to see a video explanation in a developer document, the practice of adding videos to GUI docs is quite common. It is because of various reasons.
The end goal of GUI docs is simple. It is to help a user who may or may not be familiar with the software to accomplish a particular task. For instance, to guide them on how to place an order in swiggy. The scenario is entirely different in the developer documentation. Here, the goal is to introduce developers to an API or an SDK. With that tool, the developers can try and accomplish their goal (not clearly defined); more like an ingredient, with which the developers can cook any dish. For instance, to guide a developer in extracting the weather data using an API and displaying it in their application.
The major components of an API document include details like Purpose, Endpoints, Attributes, Parameters, Sample Code, Success Response, and Error Responses. We all can collectively agree that the bandwidth to add a video or a screencast to this is minimal.
So, where can you add videos in the API documentation?
A. API Demo
Instead of having a plain text explanation on what an API does and how it works, just like GUI docs, you can have a quick how-to video for an API.
Example:
B. Explaining the purpose of an API
Another instance where you can use a video is when you explain the purpose of an API.
Example:
C. Use case and case studies
Adding use cases and examples to API documents is still a debatable topic. Many developers argue that for developers to use an API to its fullest, it is best if we do not point them in any direction. In their opinion, it might restrict the scope of an API. Nevertheless, it is always nice to have a video that explains a use case that the API solves just to give them an idea.
Developer Relations
It would not be fair if we ignore developer relations when we talk about educating developers on how to use a software product or tool. For those of you who are not familiar, DevRels help developers use your products better; In other words, help them achieve their goals using your APIs and SDKs.
A recent survey on developer relations states that 22% of DevRel tasks aim at educating and supporting developers. While technical writers try to achieve the same using documentation, DevRels incorporate different metrics. For instance, seminars, workshops, engaging developers in social media platforms, and so on.
The success and the rapid growth of the field of developer relations itself is proof of how catering to different learning styles of developers and opting for different metrics can be beneficial. They make the process of learning about a product less tedious.
It is time the technical writers and DevRels work closely and make developer documentation more engaging, easy to understand, and more accessible.
Do let me know your thoughts in the comments section.
