{"id":1390,"date":"2019-08-22T03:07:06","date_gmt":"2019-08-22T03:07:06","guid":{"rendered":"https:\/\/readmeprd.wpenginepowered.com\/?p=1390"},"modified":"2024-08-08T16:03:20","modified_gmt":"2024-08-08T21:03:20","slug":"types-of-documentation","status":"publish","type":"post","link":"https:\/\/readme.com\/resources\/types-of-documentation","title":{"rendered":"5 Types of API Documentation for a Successful API"},"content":{"rendered":"\n<p>Close your eyes and picture API documentation. You probably imagined a reference guide \u2014 that three column page that lists all the endpoints, and then enumerates all the params and options for each one. There are many different ways to document your API, however, and you\u2019ll need them all to have a successful API.<\/p>\n\n\n\n<p><strong>The Five Sections You&#8217;ll Meet In Good Docs:<\/strong><br>\u200c\u200c\ud83c\udf7d <a href=\"#recipes-and-examples\">Recipes and examples<\/a><br>\u200c\u200c\ud83d\uddfa <a href=\"#topical-guides\">Topical guides\u200c\u200c<\/a><br>\ud83d\udcd6 <a href=\"#reference-guides\">Reference guides\u200c\u200c<\/a><br>\ud83d\udcac <a href=\"#support-forums\">Support forums\u200c\u200c<\/a><br>\ud83d\udce3 <a href=\"#marketing-pages\">Marketing pages<\/a><\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"recipes-and-examples\">Recipes and examples<\/h2>\n\n\n\n<p><em>Use-case-focused tutorials with lots of examples that can be copied and pasted<\/em><\/p>\n\n\n\n<p>\u200c\u200cIf you\u2019re anything like me, when you get to a documentation page you scroll down until you see a code snippet, copy and paste it, and tweak it until it does what you want.<\/p>\n\n\n\n<figure class=\"kg-card kg-embed-card\">\n<blockquote class=\"twitter-tweet\" data-width=\"550\"><p dir=\"ltr\" lang=\"en\">Why would you ever spend a few minutes reading the documentation when you can spend a few hours randomly trying things?<\/p><p>\u2014 Ali Spittel \ud83d\udc1e (@ASpittel) <a href=\"https:\/\/twitter.com\/ASpittel\/status\/1153695013261455365?ref_src=twsrc%5Etfw\">July 23, 2019<\/a><\/p><\/blockquote>\n<p><script async=\"\" src=\"https:\/\/platform.twitter.com\/widgets.js\" charset=\"utf-8\"><\/script><\/p>\n<\/figure>\n\n\n\n<p>When writing docs, embrace this! APIs are incredibly flexible. However, there are always a few really common use cases. Create a section in your docs for use-case-driven recipes, with prominent examples that can be copied and pasted.<\/p>\n\n\n\n<p><strong>APIs tend to be modeled after how computers think: PUT the card resource, POST a charge, DELETE a user. <\/strong>But humans think in use cases. When they use your API, especially at first, they have a simple goal in mind like, \u201csend a text message,\u201d or \u201cget a list of the 10 most recent posts.\u201d<\/p>\n\n\n\n<p><strong>Walk people through a use case and include a large number of code samples. <\/strong>Think of it like a written version of sitting down and explaining to someone how to use your API. They\u2019re tutorials that take the user from start to finish and accomplish a task.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"topical-guides\">Topical guides<\/h2>\n\n\n\n<p><em>Deeper dives into advanced topics about your API<\/em><\/p>\n\n\n\n<p><strong>Topical guides are your chance to make a deeper dive into conceptual areas of your API. <\/strong>This is also where you talk about things like the philosophy underlying your API. You want users who buy into your API design, rather than fight against it.<\/p>\n\n\n\n<p>For example, let\u2019s say your API has a sandbox mode. There may be a flag in the reference guides, but this is where you talk about how to enable it, when developers should be using it, best practices around it, and more.<\/p>\n\n\n\n<p>There are a lot of decisions to make when it comes to designing an API. <strong>This is where you clear up assumptions and make sure everyone understands your API. <\/strong>Explain pagination, authorization, API keys, rate limits, models, structure, pricing, and more here.\u200c\u200cThese are often the hardest to write. When you design an API, everything is obvious to you, but that\u2019s not necessarily true to people using it. Creating a narrative explaining your API is important to set expectations and make sure people are successful.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"reference-guides\">Reference guides<\/h2>\n\n\n\n<p><em>A comprehensive description of all the ins and outs of your API<\/em><\/p>\n\n\n\n<p>Ah, reference guides. This is a detailed list of everything about your API: the endpoints, the parameters, the headers, and so on.<\/p>\n\n\n\n<p>Reference guides are a bit of a paradox. <strong>They\u2019re both the most <em>and<\/em> least important part of your documentation.<\/strong><\/p>\n\n\n\n<p>Sure, it\u2019s important \u2014 it\u2019s where you detail all the endpoints. You get into the nitty gritty about all the parameters and expected responses. Users can\u2019t see your code, so it\u2019s important you\u2019re extra explicit here about every little detail.<\/p>\n\n\n\n<p>However, it\u2019s tempting sometimes to make those your only docs. They\u2019re called reference documentation for a reason: they should be used for reference. <strong>You wouldn\u2019t hand someone a thesaurus and expect them to learn English, would you?<\/strong> In the same way, you shouldn\u2019t hand someone reference guides and expect them to learn how to use your API. Most of the heavy lifting should be done elsewhere in the documentation.<\/p>\n\n\n\n<p>So, back to that paradox about reference guides. They should be damn good. If there&#8217;s anything wrong with them, the person using them will be lost. <strong>But, if you\u2019re doing your documentation correctly, most users will never have to use them.<\/strong><\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"support-forums\">Support forums<\/h2>\n\n\n\n<p><i>Unstructured<\/i><em> edge cases your users run into<\/em>\u200c<\/p>\n\n\n\n<p><strong>Public support forums are the wild west of API documentation. <\/strong>Your regular documentation should be written like a story, and kept tight. Nobody wants to read through every weird edge case and potential pitfall. Support is your chance to have unorganized content.<\/p>\n\n\n\n<p><strong>Now, support forums only work if they\u2019re paired with a good search feature, or maybe a recommendation system at the end of a support article.<\/strong> However, they\u2019re your chance to cram in a ton of random content that people will find useful. Make sure they\u2019re public! Way too many people want to disable their public forums. For every user who actually wants to contact support, there are a bunch of others with the same problem who will just move on instead.<\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"marketing-pages\">Marketing pages<\/h2>\n\n\n\n<p><em>Convince people about why they should be investing in your API<\/em>\u200c\u200c<\/p>\n\n\n\n<p>Before anyone uses your API, you need to sell them on it. All too often, APIs are coy on the details. <strong>You\u2019re convincing someone to invest in you, so you should treat your API&#8217;s marketing page the same way you\u2019d treat any other. <\/strong>If a company is going to seriously invest in your platform, likely the decision won\u2019t be made by a single developer. Rather, a team of technical and non-technical people will decide. And hey, even if it is one random dev, you still want to put your best foot forward. <\/p>\n\n\n\n<p>People do judge an API by its cover, and much like you\u2019d sour on a website with a bad marketing homepage, you\u2019d feel the same about APIs. There isn\u2019t much specific advice for this, because every API is different. But as long as you think of your API users as, well, users, you won\u2019t go wrong. Pay a designer! Hire a copywriter! <strong>You\u2019ve spent hours documenting how you return error messages, but it\u2019s all moot if nobody makes a call.<\/strong><\/p>\n\n\n\n<h2 class=\"wp-block-heading\" id=\"things-that-don-t-seem-like-documentation\">Things that don\u2019t seem like documentation<\/h2>\n\n\n\n<p>When you say the word \u201cdocumentation,\u201d people picture paragraphs of text. Everyone has a mental image of what documentation looks like. For me, though, I have an incredibly loose definition. I consider anything that helps you understand an API and get what you need to get done to be part of your documentation.<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Error messages:<\/strong> They aren\u2019t just for computers. <a href=\"https:\/\/readme.com\/resources\/how-to-write-good-api-errors\/\">Error messages<\/a> are a great way to convey information when something goes wrong. Nobody proactively reads docs about error codes; they only care once they hit it. Rather than making them Google for it and track it down, you can use error messages to surface documentation. When you return a certain error message, always include a link to the docs with it. If you want to take it a step further, you can include variables, so when the user clicks it, they see documentation filled with their actual variables.<\/li>\n\n\n\n<li><strong>Change logs + status site:<\/strong> Is the API down, or did you just mess up? Did something change on your end or theirs? Don\u2019t make your users crawl through a ton of debugging if the problem is your API! Make sure you keep a solid log of everything that\u2019s changed and broken with your API, so your users don\u2019t have to figure it out for themselves.<\/li>\n\n\n\n<li><strong>SDKs:<\/strong> There\u2019s a lot of debate about API SDKs. Purists think they add a bunch of unnecessary cruft on top of something that\u2019s already perfectly language-agnostic. However, SDKs are great for smoothing out edge cases. Should the content be passed as form data or body params? Should it be encoded in a certain way, or have certain headers? Should the API key be a header, parameter, basic auth \u2014 who cares? An SDK abstracts away all the tiny inconsistencies and details. Rather than forcing your users to read through nuanced paragraphs of text explaining all the little details, a good SDK can cut down on a ton of documentation.<\/li>\n\n\n\n<li><strong>Integrations:<\/strong> When people decide to use your API, they likely aren\u2019t doing it because they <em>want<\/em> to write code. Rather, it\u2019s the best solution to their problem. Sometimes, I feel like we become too gatekeeper-y about our APIs. The goal shouldn\u2019t be to restrict access only to people with computer science degrees, but rather to enable anyone to accomplish their goal. Maybe that\u2019s done through Node or Python. Or maybe that\u2019s through a Zapier recipe or a Slack integration.<\/li>\n<\/ul>\n\n\n\n<p>\u200c\u200c<em>This post, and ReadMe in general, were heavily inspired by Jacob Kaplan-Moss\u2019 2009 article, \u201c<\/em><a href=\"https:\/\/jacobian.org\/2009\/nov\/10\/what-to-write\/\" rel=\"noreferrer nofollow noopener\"><em>What to Write<\/em><\/a><em>.\u201d<\/em><\/p>\n","protected":false},"excerpt":{"rendered":"<p>Close your eyes and picture API documentation. You probably imagined a reference guide \u2014 that three column page that lists all the endpoints, and then enumerates all the params and options for each one. There are many different ways to document your API, however, and you\u2019ll need them all to have a successful API. The [&hellip;]<\/p>\n","protected":false},"author":3,"featured_media":2917,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"content-type":"","inline_featured_image":false,"footnotes":""},"categories":[22,31],"tags":[42],"ppma_author":[55],"class_list":["post-1390","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-api-tips","category-behind-the-docs","tag-api-tips"],"acf":[],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v23.0 - https:\/\/yoast.com\/wordpress\/plugins\/seo\/ -->\n<title>5 Types of API Documentation for a Successful API - ReadMe: Resource Library<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/readme.com\/resources\/types-of-documentation\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"5 Types of API Documentation for a Successful API - ReadMe: Resource Library\" \/>\n<meta property=\"og:description\" content=\"Close your eyes and picture API documentation. You probably imagined a reference guide \u2014 that three column page that lists all the endpoints, and then enumerates all the params and options for each one. There are many different ways to document your API, however, and you\u2019ll need them all to have a successful API. The [&hellip;]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/readme.com\/resources\/types-of-documentation\" \/>\n<meta property=\"og:site_name\" content=\"ReadMe: Resource Library\" \/>\n<meta property=\"article:published_time\" content=\"2019-08-22T03:07:06+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2024-08-08T21:03:20+00:00\" \/>\n<meta property=\"og:image\" content=\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2019\/08\/5-Types-of-API-Docs.png\" \/>\n\t<meta property=\"og:image:width\" content=\"200\" \/>\n\t<meta property=\"og:image:height\" content=\"200\" \/>\n\t<meta property=\"og:image:type\" content=\"image\/png\" \/>\n<meta name=\"author\" content=\"Gregory Koberger\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"Sergey Bezdudnyy\" \/>\n\t<meta name=\"twitter:label2\" content=\"Est. reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"7 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/readme.com\/resources\/types-of-documentation\",\"url\":\"https:\/\/readme.com\/resources\/types-of-documentation\",\"name\":\"5 Types of API Documentation for a Successful API - ReadMe: Resource Library\",\"isPartOf\":{\"@id\":\"https:\/\/readme.com\/resources\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/readme.com\/resources\/types-of-documentation#primaryimage\"},\"image\":{\"@id\":\"https:\/\/readme.com\/resources\/types-of-documentation#primaryimage\"},\"thumbnailUrl\":\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2019\/08\/5-Types-of-API-Docs.png\",\"datePublished\":\"2019-08-22T03:07:06+00:00\",\"dateModified\":\"2024-08-08T21:03:20+00:00\",\"author\":{\"@id\":\"https:\/\/readme.com\/resources\/#\/schema\/person\/5d27caf848984b250c70a69161b76828\"},\"breadcrumb\":{\"@id\":\"https:\/\/readme.com\/resources\/types-of-documentation#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/readme.com\/resources\/types-of-documentation\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/readme.com\/resources\/types-of-documentation#primaryimage\",\"url\":\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2019\/08\/5-Types-of-API-Docs.png\",\"contentUrl\":\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2019\/08\/5-Types-of-API-Docs.png\",\"width\":200,\"height\":200},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/readme.com\/resources\/types-of-documentation#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/readme.com\/resources\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"5 Types of API Documentation for a Successful API\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/readme.com\/resources\/#website\",\"url\":\"https:\/\/readme.com\/resources\/\",\"name\":\"ReadMe: Resource Library\",\"description\":\"Making API documentation better for everyone\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/readme.com\/resources\/?s={search_term_string}\"},\"query-input\":\"required name=search_term_string\"}],\"inLanguage\":\"en-US\"},{\"@type\":\"Person\",\"@id\":\"https:\/\/readme.com\/resources\/#\/schema\/person\/5d27caf848984b250c70a69161b76828\",\"name\":\"Sergey Bezdudnyy\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/readme.com\/resources\/#\/schema\/person\/image\/8a01d0c296bdfcf8b54a6c0c0a94b904\",\"url\":\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/05\/sergey-profile-thumb.webp\",\"contentUrl\":\"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/05\/sergey-profile-thumb.webp\",\"caption\":\"Sergey Bezdudnyy\"},\"sameAs\":[\"http:\/\/auq.io\"],\"url\":\"https:\/\/readme.com\/resources\/author\/sergey-auq\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"5 Types of API Documentation for a Successful API - ReadMe: Resource Library","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/readme.com\/resources\/types-of-documentation","og_locale":"en_US","og_type":"article","og_title":"5 Types of API Documentation for a Successful API - ReadMe: Resource Library","og_description":"Close your eyes and picture API documentation. You probably imagined a reference guide \u2014 that three column page that lists all the endpoints, and then enumerates all the params and options for each one. There are many different ways to document your API, however, and you\u2019ll need them all to have a successful API. The [&hellip;]","og_url":"https:\/\/readme.com\/resources\/types-of-documentation","og_site_name":"ReadMe: Resource Library","article_published_time":"2019-08-22T03:07:06+00:00","article_modified_time":"2024-08-08T21:03:20+00:00","og_image":[{"width":200,"height":200,"url":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2019\/08\/5-Types-of-API-Docs.png","type":"image\/png"}],"author":"Gregory Koberger","twitter_card":"summary_large_image","twitter_misc":{"Written by":"Sergey Bezdudnyy","Est. reading time":"7 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/readme.com\/resources\/types-of-documentation","url":"https:\/\/readme.com\/resources\/types-of-documentation","name":"5 Types of API Documentation for a Successful API - ReadMe: Resource Library","isPartOf":{"@id":"https:\/\/readme.com\/resources\/#website"},"primaryImageOfPage":{"@id":"https:\/\/readme.com\/resources\/types-of-documentation#primaryimage"},"image":{"@id":"https:\/\/readme.com\/resources\/types-of-documentation#primaryimage"},"thumbnailUrl":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2019\/08\/5-Types-of-API-Docs.png","datePublished":"2019-08-22T03:07:06+00:00","dateModified":"2024-08-08T21:03:20+00:00","author":{"@id":"https:\/\/readme.com\/resources\/#\/schema\/person\/5d27caf848984b250c70a69161b76828"},"breadcrumb":{"@id":"https:\/\/readme.com\/resources\/types-of-documentation#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/readme.com\/resources\/types-of-documentation"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/readme.com\/resources\/types-of-documentation#primaryimage","url":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2019\/08\/5-Types-of-API-Docs.png","contentUrl":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2019\/08\/5-Types-of-API-Docs.png","width":200,"height":200},{"@type":"BreadcrumbList","@id":"https:\/\/readme.com\/resources\/types-of-documentation#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/readme.com\/resources\/"},{"@type":"ListItem","position":2,"name":"5 Types of API Documentation for a Successful API"}]},{"@type":"WebSite","@id":"https:\/\/readme.com\/resources\/#website","url":"https:\/\/readme.com\/resources\/","name":"ReadMe: Resource Library","description":"Making API documentation better for everyone","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/readme.com\/resources\/?s={search_term_string}"},"query-input":"required name=search_term_string"}],"inLanguage":"en-US"},{"@type":"Person","@id":"https:\/\/readme.com\/resources\/#\/schema\/person\/5d27caf848984b250c70a69161b76828","name":"Sergey Bezdudnyy","image":{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/readme.com\/resources\/#\/schema\/person\/image\/8a01d0c296bdfcf8b54a6c0c0a94b904","url":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/05\/sergey-profile-thumb.webp","contentUrl":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/05\/sergey-profile-thumb.webp","caption":"Sergey Bezdudnyy"},"sameAs":["http:\/\/auq.io"],"url":"https:\/\/readme.com\/resources\/author\/sergey-auq"}]}},"authors":[{"term_id":55,"user_id":0,"is_guest":1,"slug":"greg-koberger","display_name":"Gregory Koberger","avatar_url":{"url":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/06\/lSQSlvk3_400x400.jpeg","url2x":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/06\/lSQSlvk3_400x400.jpeg"},"first_name":"Gregory","last_name":"Koberger","position":"Founder, CEO","slogan":"","description":"Greg hails from the lovely town of Schaghticoke in upstate New York. After attending RIT he made the move to San Francisco where he worked for Mozilla and freelanced for a bunch of startups. He founded ReadMe after building docs sites for most of them. You can find him drinking coffee or obsessively competing for Swarm mayorships."}],"_links":{"self":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts\/1390","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/comments?post=1390"}],"version-history":[{"count":0,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts\/1390\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/media\/2917"}],"wp:attachment":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/media?parent=1390"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/categories?post=1390"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/tags?post=1390"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/ppma_author?post=1390"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}