APIs are crucial for modern business and innovation, acting as the connective tissue for software. High-quality API documentation is essential for developer adoption and success, directly impacting the developer experience and, consequently, the value derived from APIs.
Mind Map
Click to expand
Click to explore the full interactive mind map • Zoom, pan, and navigate
to the state of the developer Nation
there are currently 24.3 million active
software developers in the world
that's more than the entire population
of Florida or Australia
techies are integral to making the world
function optimally but unfortunately
quite often they spend their time not
creating value but trying to figure out
how software that someone else created works
works
as you know from our other videos on
technical documentation writing docs is
an extremely important part of creating
software that users will love but what
if developers are the users
let's talk about API documentation and
why it matters [Music]
if Engineers are helping the world
connect then apis are the most useful
tools in their toolbox
as you may know application programming
interfaces are pieces of code written
and shared specifically to help software
communicate they allow one software to
access information or functionality from
another software and they're everywhere
whether we're aware of them or not so
much so that we currently live in the
API economy API economy is the concept
of using apis to improve and optimize
your operations companies build their
own apis to automate internal processes
or use external open apis to gain access
to a wide range of functionality in
their own apps many companies wouldn't
be successful today without using apis
to jump start their services
Distributing apis has also become a
viable business model Salesforce
surveyed 800 cios and it decision makers
to reveal that a third of related
businesses revenue is being generated by
apis Brands like Salesforce eBay and
Expedia have become truly api-led by
letting startups use their resources via
apis large companies open up new
relevance for themselves and contribute
to Innovation what we have is a new and
more efficient way to grow your business
by using existing technology rather than
creating everything from scratch
so in a world where apis are a product
for consumption you should put just as
much effort towards creating and
distributing them as you would with any
software and a big part of that effort
any API exists of two things the actual
code and the documentation for using it
what if you bought a Lego set to build
your own Millennium Falcon and found
that they forgot to put the manual in
the box now all you have is a pile of
Lego pieces that is worth nothing to you
apis are the same Engineers need
documentation to know what an API can do
and how to request it and they need this
information to be comprehensive and easy
to understand
see developers interact with apis every
day sometimes for over 10 hours a week
searching for apis going on forums to
ask about apis reading reviews of apis
and rummaging in the documentation so if
you want them to use your API consider
developer experience just as you would
user experience
let's start by understanding how API
docs are usually created
most apis today are designed using an
open API specification this is a
standard format that allows devs to
describe their apis in a language
understood by humans and computers
typically yaml
this is a sample of open API definition
it's all pretty clear if you know what
you're looking at there's a version of
the specification then the name and
description for an API and where servers
are located
finally here are the individual
endpoints of an API this one allows you
to request a list of users
you can see response codes and their
meanings 200 for ok 400 for an invalid
user ID 404 for not found Etc
in theory open api's Simple structure
can help anyone make sense of an API
without docs but this would be no
different from selling a Lego set in a
big bucket with a black and white Manual
of course you can still build a
spaceship but it won't be as enjoyable
as having all the pieces pre-sorted with
the instruction printed in full color
luckily open API also allows for
automating DOT creation if your API is
written in the open API standard tools
like Postman or Swagger will pull sample
requests code Snippets and examples from
your collection and populate API docs
with them this is a big improvement from
Simply reading the specification you can
make no changes to these automated docs
and distribute them among users as is
but for many API creators this is just
the beginning to make truly great API
docs that developers will love you need
to spend a bit more time on them how
should you write documentation to
elevate the developer experience
one of the first recommendations we want
to give is to address the entry level in
your Docs
Google creates some of the best
documentation for its apis and it's no
coincidence that they are used
everywhere all the time
one of its success factors is how
beginner friendly it is Google doesn't
treat its users like pros and that's
because they often are not among Google
Maps API users are just people who want
to display a map on their website or
calculate travel times for a complex
multimodal family trip
Google understands its target audience
and that it never consists of just one
type of person generally always remember
that your API docs can be viewed by not
only professionals but also decision
makers or Tech journalists who just want
to review and compare to Target them all
target the least experienced group this
includes writing in simple English
adding links to useful sources and using
visual aids
the next thing you should be doing in
your docs is following the existing user Journey
Journey
in product management a user flow or
Journey helps the ux team map out the
app's layout to follow the natural
progression of a user's thoughts and
intentions and API users are users too
so how would they go about exploring
your API
first they'd like to know how this API
can be helpful to them that's why most
docs start with a what is section who
can use this API and how what can it do
then if they decide they want to use it
how can they access it what is the
authentication process and where can
they get a key after that how do they
actually start do they need to register
somewhere else or tick some other boxes
finally you can provide information
about specific API functions examples
statuses and errors and dive into other details
details
the third piece of advice for you is to
stick to the known layout
if you've seen a few API docs you've
seen them all API information is
typically organized in similar formats
so it's intuitive to use most
incorporate a two or three column layout
with contents on the left the main
document body in the middle and code
examples to the right study the docs of
a few popular apis to pinpoint best
practices such as the contents always
sticking to the side of the screen or
code Snippets in different languages
also remember to keep your docs updated
at all times
an API is only as good as its up to
dateness if you're using a software like
Dapper docs or redokly your docs will be
updated accordingly but you need a
maintenance strategy all the same
start by assigning someone
responsibility for updates they will
prepare docs to roll out along with
updates remove deprecated data and
analyze what endpoints might require
more tutorials and Improvement also use
the devs natural inclination to share
feedback and encourage them to rate the
page and leave likes
finally employ a person that knows how
to write technical content a technical
writer writing API docs means knowing
how to translate jargon into words that
people from different backgrounds can
understand this is typically the job of
a technical writer a tech writer is a
person who's equally good at crafting
sentences and understanding the
underlying programming logic not only
can they deliver sales copy to drive
your API revenues they will also add
helpful descriptions links examples and
tutorials before we send you off to
create great docs let's look in detail
HubSpot apis are used by those who want
to build an app those setting up a
custom integration and people looking to
extend the functionality of their
website the last group is often
marketers without any Technical Training
so HubSpot takes care of them in a few
ways the start guide is short and
straightforward and there's a section
referencing Community forums and a slack
group where users can go for help
HubSpot also has a free one and a half
hour course demonstrating what the apis
are used for and how to make them work
note that HubSpot is currently
transitioning towards a new generation
of API but they keep supporting an older
version with corresponding docs another
cool example is stripe stripe is an API
company so their docs are the main way
to attract retain and communicate with
customers an interesting section for
review is the tour of the API where the
main concepts are described in plain
English striped docs follow a familiar
three-column layout with code samples
and other important info on the right
traditionally you can choose the library
and copy the text in one click but note
a Sleek switch between light and dark
mode that many devs will surely
appreciate every section ends with the
was this helpful prompt for feedback
Salesforce already mentioned a few times
in the video also deserves a quick
overview before they even start any
integration users can review and compare
different API types depending on the
supported protocols and use cases each
type will in turn lead them to separate
documentation which also starts with
educational materials after a detailed
quick start they have an abundance of
examples with code samples to explore
apart from these you might want to pick
out some ideas from docs by twilio meta
and MailChimp to name a few
getting someone to use your product is
what marketers and product managers of
the world work hard to do in a world
where apis are a product too this effort
should spread to API creation whether
you want your internal API to be useful
to your employees or capitalize on the
service you publish commit to it and
treat the API with the respect it
deserves what aspects of tech
documentation do you want us to explain
next let us know and watch more videos
in this series we'll see you next time [Music]
[Music]
Click on any text or timestamp to jump to that moment in the video
Share:
Most transcripts ready in under 5 seconds
One-Click Copy125+ LanguagesSearch ContentJump to Timestamps
Paste YouTube URL
Enter any YouTube video link to get the full transcript
Transcript Extraction Form
Most transcripts ready in under 5 seconds
Get Our Chrome Extension
Get transcripts instantly without leaving YouTube. Install our Chrome extension for one-click access to any video's transcript directly on the watch page.
