\n- Start with the absolute basics. It’s best to assume little or no knowledge of the subject, and start from there. It’s easier to skip or omit those sections, than try to add them in at a later stage.<\/li>\n
- Stick with a single theme for the exercises and examples. One of the challenges we had was to create exercises and examples that take delegates through all the stages of developing API documentation. We decided to base these on an imaginary API for a hospital, and this turned out to be a good choice. It’s meant we can use real world examples from healthcare, \u00a0as well as ones we’ve created, during\u00a0the course.<\/li>\n
- Make the examples visceral. The more you can anchor the exercises into people’s lives and experiences, the more real and meaningful they will be for them.<\/li>\n
- Don’t get sucked into looking at only one tool. There are a number of ways to develop API documentation, and the tools are developing at a rapid pace.<\/li>\n
- Don’t be too ambitious with the exercises.<\/li>\n
- Writers want to write on a training course about documentation, so give them the opportunity to do so.<\/li>\n
- Set realistic expectations regarding coding skills. You can’t teach people how to code in multiple languages in a day, so you need to provide building blocks that they can build upon in the future.<\/li>\n<\/ul>\n
The slide deck now comprises\u00a0330 slides, and the test recordings indicate it’s a\u00a0one day course. We’re still not convinced we have the best title for the course – if you have any suggestions, do let us know.<\/p>\n","protected":false},"excerpt":{"rendered":"
We’ve written\u00a0our new training course on documenting\u00a0APIs, bar the model answers, and it’s now out for review. We’ve learnt a few lessons, and confirmed a few beliefs, whilst developing the course.\u00a0We thought we’d share them below: Start with the absolute basics. It’s best to assume little or no knowledge of the subject, and start from… Read more »<\/a><\/p>\n","protected":false},"author":3,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"jetpack_post_was_ever_published":false,"_jetpack_newsletter_access":"","_jetpack_dont_email_post_to_subs":false,"_jetpack_newsletter_tier_id":0,"_jetpack_memberships_contains_paywalled_content":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[662,145,149],"tags":[553,276,282],"class_list":["post-8993","post","type-post","status-publish","format-standard","hentry","category-api","category-technical-author","category-training","tag-api","tag-documentation","tag-training"],"acf":[],"yoast_head":"\nLessons learnt from developing our API documentation course - Cherryleaf<\/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:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/\" \/>\n<meta property=\"og:locale\" content=\"en_GB\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Lessons learnt from developing our API documentation course - Cherryleaf\" \/>\n<meta property=\"og:description\" content=\"We’ve written\u00a0our new training course on documenting\u00a0APIs, bar the model answers, and it’s now out for review. We’ve learnt a few lessons, and confirmed a few beliefs, whilst developing the course.\u00a0We thought we’d share them below: Start with the absolute basics. It’s best to assume little or no knowledge of the subject, and start from... Read more »\" \/>\n<meta property=\"og:url\" content=\"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/\" \/>\n<meta property=\"og:site_name\" content=\"Cherryleaf\" \/>\n<meta property=\"article:published_time\" content=\"2016-03-30T08:28:21+00:00\" \/>\n<meta name=\"author\" content=\"ellis\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:creator\" content=\"@cherryleafltd\" \/>\n<meta name=\"twitter:site\" content=\"@cherryleafltd\" \/>\n<meta name=\"twitter:label1\" content=\"Written by\" \/>\n\t<meta name=\"twitter:data1\" content=\"ellis\" \/>\n\t<meta name=\"twitter:label2\" content=\"Estimated reading time\" \/>\n\t<meta name=\"twitter:data2\" content=\"2 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"Article\",\"@id\":\"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/#article\",\"isPartOf\":{\"@id\":\"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/\"},\"author\":{\"name\":\"ellis\",\"@id\":\"https:\/\/www.cherryleaf.com\/#\/schema\/person\/3aac161439df53b58fcbc8bcd6bf5318\"},\"headline\":\"Lessons learnt from developing our API documentation course\",\"datePublished\":\"2016-03-30T08:28:21+00:00\",\"dateModified\":\"2016-03-30T08:28:21+00:00\",\"mainEntityOfPage\":{\"@id\":\"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/\"},\"wordCount\":323,\"commentCount\":0,\"publisher\":{\"@id\":\"https:\/\/www.cherryleaf.com\/#organization\"},\"keywords\":[\"api\",\"documentation\",\"Training\"],\"articleSection\":[\"API\",\"Technical Author\",\"Training\"],\"inLanguage\":\"en-GB\",\"potentialAction\":[{\"@type\":\"CommentAction\",\"name\":\"Comment\",\"target\":[\"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/#respond\"]}]},{\"@type\":\"WebPage\",\"@id\":\"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/\",\"url\":\"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/\",\"name\":\"Lessons learnt from developing our API documentation course - Cherryleaf\",\"isPartOf\":{\"@id\":\"https:\/\/www.cherryleaf.com\/#website\"},\"datePublished\":\"2016-03-30T08:28:21+00:00\",\"dateModified\":\"2016-03-30T08:28:21+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/#breadcrumb\"},\"inLanguage\":\"en-GB\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/www.cherryleaf.com\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Lessons learnt from developing our API documentation course\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/www.cherryleaf.com\/#website\",\"url\":\"https:\/\/www.cherryleaf.com\/\",\"name\":\"Cherryleaf\",\"description\":\"Clear instructions your users will love. Tel: +44 (0)207 100 4513\",\"publisher\":{\"@id\":\"https:\/\/www.cherryleaf.com\/#organization\"},\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/www.cherryleaf.com\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-GB\"},{\"@type\":\"Organization\",\"@id\":\"https:\/\/www.cherryleaf.com\/#organization\",\"name\":\"Cherryleaf\",\"url\":\"https:\/\/www.cherryleaf.com\/\",\"logo\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-GB\",\"@id\":\"https:\/\/www.cherryleaf.com\/#\/schema\/logo\/image\/\",\"url\":\"https:\/\/www.cherryleaf.com\/wp-content\/uploads\/2018\/02\/cherryleaf-logo-snagit.png\",\"contentUrl\":\"https:\/\/www.cherryleaf.com\/wp-content\/uploads\/2018\/02\/cherryleaf-logo-snagit.png\",\"width\":435,\"height\":121,\"caption\":\"Cherryleaf\"},\"image\":{\"@id\":\"https:\/\/www.cherryleaf.com\/#\/schema\/logo\/image\/\"},\"sameAs\":[\"https:\/\/x.com\/cherryleafltd\",\"https:\/\/www.youtube.com\/channel\/UCQQmJCmDrCqEAmBhinq0CIQ\"]},{\"@type\":\"Person\",\"@id\":\"https:\/\/www.cherryleaf.com\/#\/schema\/person\/3aac161439df53b58fcbc8bcd6bf5318\",\"name\":\"ellis\",\"image\":{\"@type\":\"ImageObject\",\"inLanguage\":\"en-GB\",\"@id\":\"https:\/\/www.cherryleaf.com\/#\/schema\/person\/image\/\",\"url\":\"https:\/\/secure.gravatar.com\/avatar\/9c3553ccbc10f078e4acf1f1f8f3b6df?s=96&r=pg\",\"contentUrl\":\"https:\/\/secure.gravatar.com\/avatar\/9c3553ccbc10f078e4acf1f1f8f3b6df?s=96&r=pg\",\"caption\":\"ellis\"},\"sameAs\":[\"https:\/\/www.cherryleaf.com\"],\"url\":\"https:\/\/www.cherryleaf.com\/author\/ellis\/\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Lessons learnt from developing our API documentation course - Cherryleaf","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:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/","og_locale":"en_GB","og_type":"article","og_title":"Lessons learnt from developing our API documentation course - Cherryleaf","og_description":"We’ve written\u00a0our new training course on documenting\u00a0APIs, bar the model answers, and it’s now out for review. We’ve learnt a few lessons, and confirmed a few beliefs, whilst developing the course.\u00a0We thought we’d share them below: Start with the absolute basics. It’s best to assume little or no knowledge of the subject, and start from... Read more »","og_url":"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/","og_site_name":"Cherryleaf","article_published_time":"2016-03-30T08:28:21+00:00","author":"ellis","twitter_card":"summary_large_image","twitter_creator":"@cherryleafltd","twitter_site":"@cherryleafltd","twitter_misc":{"Written by":"ellis","Estimated reading time":"2 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"Article","@id":"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/#article","isPartOf":{"@id":"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/"},"author":{"name":"ellis","@id":"https:\/\/www.cherryleaf.com\/#\/schema\/person\/3aac161439df53b58fcbc8bcd6bf5318"},"headline":"Lessons learnt from developing our API documentation course","datePublished":"2016-03-30T08:28:21+00:00","dateModified":"2016-03-30T08:28:21+00:00","mainEntityOfPage":{"@id":"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/"},"wordCount":323,"commentCount":0,"publisher":{"@id":"https:\/\/www.cherryleaf.com\/#organization"},"keywords":["api","documentation","Training"],"articleSection":["API","Technical Author","Training"],"inLanguage":"en-GB","potentialAction":[{"@type":"CommentAction","name":"Comment","target":["https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/#respond"]}]},{"@type":"WebPage","@id":"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/","url":"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/","name":"Lessons learnt from developing our API documentation course - Cherryleaf","isPartOf":{"@id":"https:\/\/www.cherryleaf.com\/#website"},"datePublished":"2016-03-30T08:28:21+00:00","dateModified":"2016-03-30T08:28:21+00:00","breadcrumb":{"@id":"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/#breadcrumb"},"inLanguage":"en-GB","potentialAction":[{"@type":"ReadAction","target":["https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/www.cherryleaf.com\/2016\/03\/lessons-learnt-from-developing-the-api-documentation-course\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/www.cherryleaf.com\/"},{"@type":"ListItem","position":2,"name":"Lessons learnt from developing our API documentation course"}]},{"@type":"WebSite","@id":"https:\/\/www.cherryleaf.com\/#website","url":"https:\/\/www.cherryleaf.com\/","name":"Cherryleaf","description":"Clear instructions your users will love. Tel: +44 (0)207 100 4513","publisher":{"@id":"https:\/\/www.cherryleaf.com\/#organization"},"potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/www.cherryleaf.com\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-GB"},{"@type":"Organization","@id":"https:\/\/www.cherryleaf.com\/#organization","name":"Cherryleaf","url":"https:\/\/www.cherryleaf.com\/","logo":{"@type":"ImageObject","inLanguage":"en-GB","@id":"https:\/\/www.cherryleaf.com\/#\/schema\/logo\/image\/","url":"https:\/\/www.cherryleaf.com\/wp-content\/uploads\/2018\/02\/cherryleaf-logo-snagit.png","contentUrl":"https:\/\/www.cherryleaf.com\/wp-content\/uploads\/2018\/02\/cherryleaf-logo-snagit.png","width":435,"height":121,"caption":"Cherryleaf"},"image":{"@id":"https:\/\/www.cherryleaf.com\/#\/schema\/logo\/image\/"},"sameAs":["https:\/\/x.com\/cherryleafltd","https:\/\/www.youtube.com\/channel\/UCQQmJCmDrCqEAmBhinq0CIQ"]},{"@type":"Person","@id":"https:\/\/www.cherryleaf.com\/#\/schema\/person\/3aac161439df53b58fcbc8bcd6bf5318","name":"ellis","image":{"@type":"ImageObject","inLanguage":"en-GB","@id":"https:\/\/www.cherryleaf.com\/#\/schema\/person\/image\/","url":"https:\/\/secure.gravatar.com\/avatar\/9c3553ccbc10f078e4acf1f1f8f3b6df?s=96&r=pg","contentUrl":"https:\/\/secure.gravatar.com\/avatar\/9c3553ccbc10f078e4acf1f1f8f3b6df?s=96&r=pg","caption":"ellis"},"sameAs":["https:\/\/www.cherryleaf.com"],"url":"https:\/\/www.cherryleaf.com\/author\/ellis\/"}]}},"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"jetpack-related-posts":[],"_links":{"self":[{"href":"https:\/\/www.cherryleaf.com\/wp-json\/wp\/v2\/posts\/8993","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.cherryleaf.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.cherryleaf.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.cherryleaf.com\/wp-json\/wp\/v2\/users\/3"}],"replies":[{"embeddable":true,"href":"https:\/\/www.cherryleaf.com\/wp-json\/wp\/v2\/comments?post=8993"}],"version-history":[{"count":0,"href":"https:\/\/www.cherryleaf.com\/wp-json\/wp\/v2\/posts\/8993\/revisions"}],"wp:attachment":[{"href":"https:\/\/www.cherryleaf.com\/wp-json\/wp\/v2\/media?parent=8993"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.cherryleaf.com\/wp-json\/wp\/v2\/categories?post=8993"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.cherryleaf.com\/wp-json\/wp\/v2\/tags?post=8993"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}