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