{"id":380,"date":"2024-05-22T12:54:10","date_gmt":"2024-05-22T17:54:10","guid":{"rendered":"https:\/\/readmeprd.wpenginepowered.com\/?p=380"},"modified":"2024-11-02T17:58:18","modified_gmt":"2024-11-02T22:58:18","slug":"why-you-should-let-robots-help-you-write-your-api-documentation","status":"publish","type":"post","link":"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation","title":{"rendered":"Why You Should Let Robots Help You Write Your API Documentation"},"content":{"rendered":"\n<p><\/p>\n\n\n\n<p>Creating clear, beautiful documentation is one of the biggest pains of being a developer. That&#8217;s why autodoc tools like Rdoc are so appealing. Type a line in your terminal, and like magic, you get an HTML file filled with your API specs.<\/p>\n\n\n\n<p>The problem is that the results end up looking like this:<\/p>\n\n\n\n<style>\n.custom-code-block {\n    background-color: #2e3440;\n    color: #d4d4d4;\n    padding: 16px;\n    border-radius: 8px;\n    font-size: 14px;\n    line-height: 1.5;\n    overflow-x: auto;\n}\n\n.custom-code-block .comment {\n    color: #4c566a;\n}\n\n.custom-code-block .keyword {\n    color: #89b3b3;\n    font-weight: bold;\n}\n\n.custom-code-block .variable {\n    color: #89b3b3;\n}\n\n.custom-code-block .string {\n    color: #a3be8c; \n}\n<\/style>\n\n<div class=\"custom-code-block\">\n<pre><code>\n<span class=\"comment\"># Generic Namespace exception class<\/span>\n<span class=\"keyword\">class<\/span> <span class=\"variable\">Namespace<\/span> <span class=\"variable\">Error<\/span> &lt; Standard <span class=\"variable\">Error<\/span>\n<span class=\"keyword\">end<\/span>\n\n<span class=\"comment\"># Raised when...<\/span>\n<span class=\"keyword\">class<\/span> <span class=\"variable\">SpecificError<\/span> &lt; NamespaceError\n<span class=\"keyword\">end<\/span>\n<\/code><\/pre>\n<\/div>\n\n\n\n\n<p>In 2009, Django founder Jacob Kaplan-Moss pointed out that &#8220;most of the time it&#8217;s <em>easier<\/em> just to read the source than to navigate the bullshit that these <a href=\"https:\/\/jacobian.org\/writing\/what-to-write\/\">autodoc tools produce<\/a>.&#8221;<\/p>\n\n\n\n<p>He has a point. Taking a computer-generated doc and sticking it on your developer site is like handing someone a dictionary and asking them to learn English. They&#8217;re great when someone&#8217;s stuck or needs to look something up, but with only a dictionary, nobody can properly learn.<\/p>\n\n\n\n<p>Computer-generated tools are now sophisticated enough to do a lot of the heavy lifting\u2014but they won&#8217;t show people how to actually use your API.<\/p>\n\n\n\n<p>It&#8217;s up to you to take care of the last mile, and provide people with enough context to get started with your API. By using a mix of auto-generated tools and a human touch, you can get more people up and running with your API and straight into your app.<\/p>\n\n\n\n<p><strong>Where Autodoc Tools Come into Play<\/strong><\/p>\n\n\n\n<p>Once upon a time, if you wanted to include code snippets for how to use your API in a different language, or a reference library for each GET and POST call, you had to mark them up by hand. This meant that documentation took forever to produce, was often filled with errors, and had to be updated every time the source code changed.<\/p>\n\n\n\n<p>Tools like <a href=\"http:\/\/swagger.io\/\">Swagger<\/a> and <a href=\"https:\/\/apiblueprint.org\/\">API Blueprint<\/a> make this a thing of the past. Autodoc tools now take care of a lot of the headaches around producing great documentation.<\/p>\n\n\n\n<p><a href=\"https:\/\/clearbit.com\/\">Clearbit<\/a>&#8216;s documentation does this beautifully. You can use Clearbit&#8217;s API to find out everything you need to know about a lead, from their company to their email address. Clearbit automatically generates code snippets Ruby, Node, Python, as well as a Unix shell\u2014making it easy for users to get start prospect right off the bat.<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2016\/08\/Screenshot-2016-08-10-15-34-18.png\" alt=\"\"\/><\/figure>\n\n\n\n<p><\/p>\n\n\n\n<p>Autodoc tools are great for producing:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>The skeleton of your docs.<\/strong> Good APIs speak in a common language that everyone can understand, which is one of the reasons why <a href=\"https:\/\/blog.readme.io\/what-is-swagger-and-why-it-matters\/\">we love Swagger<\/a>. Swagger provides the blueprint for your API documentation. It takes in your JSON or YAML file, and spits out an interactive doc and a roadmap for building out your API even further.<\/li>\n\n\n\n<li><strong>Reference libraries.<\/strong> An API&#8217;s reference library gives an overview of all the different REST calls possible with the API. Swagger, RAML, and API Blueprint all help you parse your app&#8217;s code and turn it into a library. Having a reference library is important for seasoned developers who already know how to use an API, but it won&#8217;t be enough for everyone else.<\/li>\n\n\n\n<li><strong>Code snippets.<\/strong> If you include the code snippets for 6 popular languages on your documentation site, with 15 API endpoints, this means 90 code snippets to keep up to date. Autodoc tools like Swagger and API Blueprint take care of this for you, and automatically update when you change the source code.<\/li>\n<\/ul>\n\n\n\n<p>As you improve your product, your API will be able to do more things\u2014but it will also grow more complex. Autodoc tools allow you to scale your documentation with what you&#8217;re building.<\/p>\n\n\n\n<p><strong>You Need a Human Touch&#8230;.For Now<\/strong><\/p>\n\n\n\n<p>While computer-generated tools can produce resources, they&#8217;re not great at actually welcoming people into your API. They don&#8217;t know what parts of your API are more important and should be emphasized, nor do they provide examples of how to actually plug your API into someone&#8217;s app.<\/p>\n\n\n\n<p>That&#8217;s up to you. Humans understand other humans. They can describe how the API works in plain English, provide concrete use-cases and examples, and help someone without much coding experience to get off the ground making calls. That&#8217;s why it&#8217;s so important to get a human touch in your API documentation.<\/p>\n\n\n\n<p>Mailgun, for example, uses autodoc tools to generate your standard API reference library and code snippets. But its documentation is clearly written by a person, to a person. In a handy quick-start guide for new users, Mailgun&#8217;s documentation strikes a conversational tone\u2014\u201cIt&#8217;s up to you, whatever you find is easier is fine with us.\u201d<\/p>\n\n\n\n<figure class=\"wp-block-image\"><img decoding=\"async\" src=\"https:\/\/blog.readme.com\/content\/images\/2016\/08\/Screenshot-2016-08-10-16-05-26.png\" alt=\"\"\/><\/figure>\n\n\n\n<p><\/p>\n\n\n\n<p>Let computers do the heavy lifting, and let the humans reorganize that information in a way that will make sense to other humans.<\/p>\n\n\n\n<p>Getting real people to help craft your documentation allows you to:<\/p>\n\n\n\n<ul class=\"wp-block-list\">\n<li><strong>Explain the edge-cases:<\/strong> Your API will always have specific edge-cases and utilities that aren&#8217;t covered by tools like Swagger. Maybe, like Twilio, your app allows calls to your API to trigger text messages or phone calls. An autodoc tool won&#8217;t be able to understand that, let alone explain it.<\/li>\n\n\n\n<li><strong>Humanize documentation:<\/strong> Autodoc tools tend to spit out lines in documentation like \u201cPOST \/user\/new\u201d Your documentation becomes much friendlier when you replace that with a title like \u201cCreate New User.\u201d<\/li>\n\n\n\n<li><strong>Handle errors and common mistakes:<\/strong> Robots assume that everyone who uses your API is also a robot. In reality, many of the people who take your API for a test-drive won&#8217;t be perfect coders. Provide them with a common mistakes section in your documentation.<\/li>\n<\/ul>\n\n\n\n<p>There&#8217;s no AI super-power (yet) that will magically cook up your documentation. If you rely 100% on autodoc tools, you end up with a bunch of static HTML files. The results are only legible if there&#8217;s a human on the other end to put together the pieces of the puzzle.<\/p>\n\n\n\n<p><strong>Robots + Humans<\/strong><\/p>\n\n\n\n<p>Some of the people who use your API will be seasoned developers who only need a reference manual to get off the ground. Others will be novices who are interested in both.<\/p>\n\n\n\n<p>The best API documentation leverages both tools <em>and<\/em> human resources to create a tailored experience for every type of customer.<\/p>\n\n\n\n<p>Create documentation that&#8217;s as clear for a developer at Facebook, as it is for the kid in Korea who&#8217;s building the next Facebook. That&#8217;s what will get your API actually used by the bigger software ecosystem.<\/p>\n\n\n","protected":false},"excerpt":{"rendered":"<p>Creating clear, beautiful documentation is one of the biggest pains of being a developer. That&#8217;s why autodoc tools like Rdoc are so appealing. Type a line in your terminal, and like magic, you get an HTML file filled with your API specs. The problem is that the results end up looking like this: # Generic [&hellip;]<\/p>\n","protected":false},"author":3,"featured_media":370,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"content-type":"","inline_featured_image":false,"footnotes":""},"categories":[22,30],"tags":[42],"ppma_author":[3],"class_list":["post-380","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-api-tips","category-apis-101","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>Why You Should Let Robots Help You Write Your API Documentation - 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\/why-you-should-let-robots-help-you-write-your-api-documentation\" \/>\n<meta property=\"og:locale\" content=\"en_US\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Why You Should Let Robots Help You Write Your API Documentation - ReadMe: Resource Library\" \/>\n<meta property=\"og:description\" content=\"Creating clear, beautiful documentation is one of the biggest pains of being a developer. That&#8217;s why autodoc tools like Rdoc are so appealing. Type a line in your terminal, and like magic, you get an HTML file filled with your API specs. The problem is that the results end up looking like this: # Generic [&hellip;]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation\" \/>\n<meta property=\"og:site_name\" content=\"ReadMe: Resource Library\" \/>\n<meta property=\"article:published_time\" content=\"2024-05-22T17:54:10+00:00\" \/>\n<meta property=\"article:modified_time\" content=\"2024-11-02T22:58:18+00:00\" \/>\n<meta name=\"author\" content=\"Sergey Bezdudnyy\" \/>\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=\"5 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation\",\"url\":\"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation\",\"name\":\"Why You Should Let Robots Help You Write Your API Documentation - ReadMe: Resource Library\",\"isPartOf\":{\"@id\":\"https:\/\/readme.com\/resources\/#website\"},\"primaryImageOfPage\":{\"@id\":\"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation#primaryimage\"},\"image\":{\"@id\":\"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation#primaryimage\"},\"thumbnailUrl\":\"\",\"datePublished\":\"2024-05-22T17:54:10+00:00\",\"dateModified\":\"2024-11-02T22:58:18+00:00\",\"author\":{\"@id\":\"https:\/\/readme.com\/resources\/#\/schema\/person\/5d27caf848984b250c70a69161b76828\"},\"breadcrumb\":{\"@id\":\"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation#breadcrumb\"},\"inLanguage\":\"en-US\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation\"]}]},{\"@type\":\"ImageObject\",\"inLanguage\":\"en-US\",\"@id\":\"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation#primaryimage\",\"url\":\"\",\"contentUrl\":\"\"},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/readme.com\/resources\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Why You Should Let Robots Help You Write Your API Documentation\"}]},{\"@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":"Why You Should Let Robots Help You Write Your API Documentation - 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\/why-you-should-let-robots-help-you-write-your-api-documentation","og_locale":"en_US","og_type":"article","og_title":"Why You Should Let Robots Help You Write Your API Documentation - ReadMe: Resource Library","og_description":"Creating clear, beautiful documentation is one of the biggest pains of being a developer. That&#8217;s why autodoc tools like Rdoc are so appealing. Type a line in your terminal, and like magic, you get an HTML file filled with your API specs. The problem is that the results end up looking like this: # Generic [&hellip;]","og_url":"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation","og_site_name":"ReadMe: Resource Library","article_published_time":"2024-05-22T17:54:10+00:00","article_modified_time":"2024-11-02T22:58:18+00:00","author":"Sergey Bezdudnyy","twitter_card":"summary_large_image","twitter_misc":{"Written by":"Sergey Bezdudnyy","Est. reading time":"5 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation","url":"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation","name":"Why You Should Let Robots Help You Write Your API Documentation - ReadMe: Resource Library","isPartOf":{"@id":"https:\/\/readme.com\/resources\/#website"},"primaryImageOfPage":{"@id":"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation#primaryimage"},"image":{"@id":"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation#primaryimage"},"thumbnailUrl":"","datePublished":"2024-05-22T17:54:10+00:00","dateModified":"2024-11-02T22:58:18+00:00","author":{"@id":"https:\/\/readme.com\/resources\/#\/schema\/person\/5d27caf848984b250c70a69161b76828"},"breadcrumb":{"@id":"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation#breadcrumb"},"inLanguage":"en-US","potentialAction":[{"@type":"ReadAction","target":["https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation"]}]},{"@type":"ImageObject","inLanguage":"en-US","@id":"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation#primaryimage","url":"","contentUrl":""},{"@type":"BreadcrumbList","@id":"https:\/\/readme.com\/resources\/why-you-should-let-robots-help-you-write-your-api-documentation#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/readme.com\/resources\/"},{"@type":"ListItem","position":2,"name":"Why You Should Let Robots Help You Write Your API Documentation"}]},{"@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":3,"user_id":3,"is_guest":0,"slug":"sergey-auq","display_name":"Sergey Bezdudnyy","avatar_url":{"url":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/05\/sergey-profile-thumb.webp","url2x":"https:\/\/readme.com\/resources\/wp-content\/uploads\/2024\/05\/sergey-profile-thumb.webp"},"first_name":"Sergey","last_name":"Bezdudnyy","position":"WordPress Developer","slogan":"Music \ud83c\udfb6\r\n\r\n<br>\r\n\r\nContent Marketing\r\n<br>\r\n&amp; More","description":"Today we\u2019ve got a special guest on the blog\u2014Ceci Stallsmith! If you were at API Mixtape 2023, you got to see her in action as a speaker. If you missed her talk, you\u2019re in luck, because today\u2019s post is covering the same topic: how to create developer marketing that doesn\u2019t suck.\r\n<br><br>\r\nToday we\u2019ve got a special guest on the blog\u2014Ceci Stallsmith! If you were at API Mixtape 2023, you got to see her in action as a speaker. If you missed her talk, you\u2019re in luck, because today\u2019s post is covering the same topic: how to create developer marketing that doesn\u2019t suck."}],"_links":{"self":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts\/380","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=380"}],"version-history":[{"count":0,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/posts\/380\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/"}],"wp:attachment":[{"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/media?parent=380"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/categories?post=380"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/tags?post=380"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/readme.com\/resources\/wp-json\/wp\/v2\/ppma_author?post=380"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}