What does an API technical writer do? And what are some of the responsibilities
aspiring writers can expect on the job? In this video, we're gonna
break down the job description of an API technical writer. And hi there. My name is Josh and I'm the founder of
Technical Writer hq, and I have over 10 years of technical writing experience. And today we'll be talking specifically
about API technical writers, what their job role and responsibilities look
like, and we'll take a look at some examples of API technical writing. And if you're not familiar
with this line of. Don't worry, that's what I'm here for. But before we dive into the topic, make
sure to subscribe to channel so you can keep up to date with everything. Technical writing if you
want to better your career. And that way you'll always get great
content that helps you, whether that's to increase your salary, increase
your skill and technical writing, or better work with stakeholders
and in many different aspects. Now that said, let's go ahead and jump in. So what exactly is an API technical. An API technical writer creates
documentation that explains how an application programming
interface or API works. They provide use case examples to
describe the most effective ways to use the interface and provide
in depth descriptions of the API's functions and how it interacts with
the application and in case the API is complex or needs better under. On the user's part, writers will build
tutorials for users on how to implement the api and last year's API writers will
make arguments in favor of how the API. Is used in its interactions with
the host system, and unlike most industrial technical documents, API
documents are a hybrid of visuals such as screenshots and written material. With that in mind, API technical
writers have to create a well defined starting point for developers to
get acquainted with the new api. This gives 'em a solid direction
to start planning, designing, and building The feature. Writers also have to structure
the document to facilitate the most common use cases for the api. For example, if the API performs
a set of actions that end users commonly implement, then that will
prominently show and the documentation. One important aspect of the technical
writer's job is to ensure that documents are written and not just for high level
developers and engineers, but also for people with less technical understanding. They'll write in a balanced tone
while ensuring there's value for users throughout the document. The documents themselves. Need to contain examples, code
samples, authentication, and other resources to be valuable to readers. To do this, writers have to
write comprehensively and support their arguments at every step. Use cases serve as a prime example based
argument in favor of the api, and writers have to know the most common uses, which
ones are important enough to be featured, and which ones developers value the. In order to do this, writers
will research comments, usage examples for their type of api. They'll also determine the most
important use cases among them based on how big a problem they solve. On the end product for the end user,
and then they'll shortlist The more high value API feature uses for developers,
all this is to create a developer first tone throughout the documentation and
to make it sound like the documentation was created to help them specifically. And the most significant part of
the API document is of course, the list of functions and API technical
writers have three responsibilities. And the first one is they have to
list the functions according to the value for the end user, right? And the second one is they have
to create structured lists that explain functions in order usually
from the most to least prominent. And number three, they have to highlight
the more prominent functions to retain developer focus and the product. And if we look at the purpose of
the documentation, Is to introduce developers to your product. User tutorials serve as an extension to
that introduction, and most API documents come with a comprehensive user tutorial
that often has a step by step instruction on how to optimally use or implement the
API to create a valuable user tutorial. Writers will analyze user compet. Determine how easily developers will
understand API features based on their own programming and design knowledge. And then they'll optimize a developer
experience, or in other words, dx, by showing developers API features
and functions in a way that doesn't overload devs with information
that's of little value to them. They'll create comprehensive modules for
each set of features, effectively breaking the tutorial up and more digestible chunks
and improving the developer experience. And lastly, they'll. A lot of visual aids, such as
flowcharts, interactive graphics, and other images to help developers
understand what the APIs are all about. Now, it really depends on the API and
the simplicity of it, or the complexity of it in terms of the amount of graphics
that you'll need to use, and we've talked about the parts of the documentation
that involves explaining what API does. However, there's also the matter
of directly convincing users that's effective at what it. This is where usage arguments come in. An important aspect of making a usage
argument in favor of an API is to get direct feedback from the users
who have studied the documentation thus far, or have sat through a
tutorial presentation about its usage. This again, falls to the writer to do api. Technical writers will
actively encourage developer. On any of the APIs features, they
could do it after each module of the documentation or towards the end. And for this, they have to include
feedback sections where developers can provide their thoughts and questions. And most writers will insert many
surveys for the same purpose in or towards the end of the document. And all of this is just to get
an idea of what the developers actually think of the api. They can use that information to then. A positive argument for the API
and support the arguments with data such as use its metrics of specific
features, developer opinions about competing APIs and much more. And now that we've discussed API
technical writing process, let's go ahead and look into what actually
goes into an API technical document. And although there are APIs of different
sizes and scope, That will have documents with more or less content. Every such document
will have five sections. These are a quick start guide,
which is a shortened version or a summary of the entire document. Also some authentication info
that explains how the API will certify user identity. When you access the API's functions,
as well as a definition of all the endpoints and an explanation of what
each endpoint does, as well as some code snippet examples and example
responses in several languages and formats in order to help users. Expect responses. Now let's go ahead and look at
each modules separately in order to learn what each entails. A quick start guide is meant
to familiarize the users with the API from the get go. It makes it easier for them to
understand how the API works in practice and what level of functionality
the finished product will have. Most running guides have a brief overview
of API and its purpose, as well as a description of his major function. In the case of Interactive Guides, the
guide will have the API interface with its core functionality to help writers
demonstrate how everything works. And if the interface is under
development, the document will contain some sample app interfaces to give
an idea of what the new API will be able to do, and the authentication
information explains how the API, I. Who is trying to access its functions. Depending on the app's complexity,
the API could have several authentication mechanisms in
place to ensure secure access. The writer will define each of
the mechanisms and explain why the API prefers that system. They'll also explain how complex
the authentication framework is and how many layers of authentication
are built into the api. Of course, all this information
will be in a structured layout to avoid making a section. Overly complex. Here's an example of an API
authentication from a Stripe api, which is an online payment service. Each API document set will have a
dedicated authentication section that looks similar to this and explains how
the API authenticates access requests, despite their name endpoints, actually
define the points where a user starts to interact with the application. They're extremely important to the
document because they explain how any. We'll begin to interact with the API
and writers will start by identifying all the endpoints present in both
the Quickstar interface and the final product, all while talking about
how they relate to other endpoints. And this includes both the primary ones
and any sister endpoints that they have. And of course, they'll explain
the functions of each endpoint going over whether the functions
are open or user restricted. Among other specifics, they'll also find
any limitations that each endpoint has co snippets are necessary to include in
documentation because most of the time developers understand API functionality. Better through code instead
of verbal or written mediums. In considering that writers have to
include code samples to explain how each sample relates various endpoints and tasks
as mentioned earlier, this is to explain how each endpoint interacts with the other
writers have to discuss the responses that each snippet of code will invoke,
and how making specific tweaks to the code will result in changes to the functions. Snippets have to be included with the
description of every function and end. This is just so Des can understand
and use them more effectively. Here's an example of coat snippets
included in complete API documentation. And again, I got this from a
resource that shows a sample of an API designed for a weather app. And this shows coat snippets in both PHP
and Ruby programming languages typically. There will be multiple snippets like
these in a set of API documents. This is to accommodate developers who
may be using different languages to program components, and each endpoint
request has an expected response. That's part of the API documentation. Writers have to pair responses with
their corresponding endpoint in order to explain how the API will
respond to user input, and they have to use language specific pairings to
ensure that a function that has been programmed in a specific language. Also has a response that's
explained in that language as well. And last year, they have to define
responses according to the request, whether that's a general request,
so that means that invokes a general response or a specific request that
elicits a request based response. And there you have it. We just went over what an API
technical writer does, their typical responsibilities on the
job, and a number of API examples and types of API documentation. Thank you so much for watching the video. If you enjoy this video, make sure to
go ahead and like the video, subscribe to our channel so you can keep up to
date with everything technical writing. And again, my name is Josh. I'm the founder of Technical Writer
hq, and I wish you the best of success in your technical writing career. If you're looking to learn more
about API technical writing, we do teach it in our certification. On Technical Writer hq. So go ahead and check it out
if you're really looking to level up your game there. And again, I'll see you on some of our
following videos where you'll learn even more about technical writing. Cheers.
