From 9581b3bf6e92c52efc5fcddeabdecebe14765cf8 Mon Sep 17 00:00:00 2001 From: Tom Johnson Date: Tue, 25 Dec 2018 13:43:48 -0800 Subject: [PATCH] fixing typos --- .../docapis_best_practices_with_api.md | 2 +- .../docapis_doc_getting_started_section.md | 4 +-- .../docapis_doc_quick_reference_guide.md | 18 +++++------ .../docapis_glossary_section.md | 18 +++++------ .../docapis_nonref_activity.md | 2 +- .../docapis_sdks_and_sample_apps.md | 24 +++++++------- .../pubapis_api_list.md | 4 +-- .../pubapis_design_patterns.md | 32 +++++++++---------- .../pubapis_overview.md | 20 ++++++------ .../content/activities/api_doc_patterns.md | 2 +- 10 files changed, 63 insertions(+), 63 deletions(-) diff --git a/_docs/documenting_nonreference_content/docapis_best_practices_with_api.md b/_docs/documenting_nonreference_content/docapis_best_practices_with_api.md index 06967d2e..e6298a54 100644 --- a/_docs/documenting_nonreference_content/docapis_best_practices_with_api.md +++ b/_docs/documenting_nonreference_content/docapis_best_practices_with_api.md @@ -40,7 +40,7 @@ Mailchimp's API best practices include tips about fault tolerance, using specifi {% include course_image.html url="https://developers.coinbase.com/api/v2#pagination" filename="bestpractices_coinbase" ext_print="png" ext_web="png" alt="Coinbase best practices" caption="Mailchimp best practices" %} -Coinbase doesn't specifically refer to these topics as best practices; instead the navigation just shows a laundry list of topics. Pagination is one of these topics worth expanding on here. What is pagination in relation to an API? Suppose your API endpoint returns all items in a user account. There could be thousands of items, and if all items were returned in the same response, it might take a long time for the API to gather and return the large amount of data. As a result, just like with searches on Google, the response returns a limited set, such as the first 10 items, and then includes a URL that you can use to go to the next set of responses. Pagination refers to advancing to the next page of responses. +Coinbase doesn't specifically refer to these topics as best practices; instead, the navigation shows a laundry list of topics. Pagination is one of these topics worth expanding on here. How does pagination relate to APIs? Suppose your API endpoint returns all items in a user account. There could be thousands of items, and if all items were returned in the same response, it might take a long time for the API to gather and return the large amount of data. As a result, just like with searches on Google, the response returns a limited set, such as the first ten items, and then includes a URL that you can use to go to the next set of responses. Pagination refers to advancing to the next page of responses. Earlier, when defining the characteristics of REST, I mentioned [HATEOS](docapis_what_is_a_rest_api.html#stateless_and_cacheable), or "Hypermedia as the Engine of Application State." Links in responses that return more results is one example of HATEOS. diff --git a/_docs/documenting_nonreference_content/docapis_doc_getting_started_section.md b/_docs/documenting_nonreference_content/docapis_doc_getting_started_section.md index dad89f70..28fa966d 100644 --- a/_docs/documenting_nonreference_content/docapis_doc_getting_started_section.md +++ b/_docs/documenting_nonreference_content/docapis_doc_getting_started_section.md @@ -22,7 +22,7 @@ The Getting Started topic is somewhat like the typical Hello World tutorial in d {% include course_image.html size="medium" filename="timetohelloworld" ext_print="png" ext_web="svg" alt="Getting started tutorials are like Hello World tutorials." caption="Think of getting started tutorials as a kind of Hello World tutorial with the API. How long would it take for a developer to get the simplest possible response using your API?" %} -Both Hello World tutorials and Getting Started tutorials share the same goal: to show a user how to use a framework, API, or some other system to get the simplest and easiest result, so they get a beginning-to-end sense of how it works. +Both Hello World tutorials and Getting Started tutorials share the same goal: to show a user how to use a framework, API, or some other system to get the simplest and easiest result, so they get a end-to-end sense of how it works. As an example, you could take a common, basic use case for your API and show how to construct a request, as well as what response returns. If a developer can make that call successfully, he or she can probably be successful with the other calls too. @@ -132,7 +132,7 @@ The Watson and IBM Cloud getting started tutorial lists three steps. It's not an With the [open-source project you identified](docapis_find_open_source_project.html), identify the getting started tutorial. Then answer the following questions: 1. Does the API have a getting started tutorial? -2. Does the getting started tutorial walk you through a beginning-to-end scenario? +2. Does the getting-started tutorial walk you through an end-to-end scenario? 3. Can you follow all the steps in the getting started tutorial successfully? 4. How long does the getting started tutorial take to complete? 5. In an attempt to simplify the instruction and keep it brief, does the documentation make assumptions about your technical level and familiarity with the domain? diff --git a/_docs/documenting_nonreference_content/docapis_doc_quick_reference_guide.md b/_docs/documenting_nonreference_content/docapis_doc_quick_reference_guide.md index 7566b987..c9078c77 100644 --- a/_docs/documenting_nonreference_content/docapis_doc_quick_reference_guide.md +++ b/_docs/documenting_nonreference_content/docapis_doc_quick_reference_guide.md @@ -9,7 +9,7 @@ section: docnonref path1: /docnonref.html --- -Quick reference guides serve a different function than [getting started tutorials](docapis_doc_getting_started_section.html). While the getting started tutorial helps beginners get oriented by providing an beginning-to-end instruction to make a simple API request, the quick reference guide helps users get a glimpse of the system as a whole, often by providing a list of the API's endpoints. +Quick reference guides serve a different function than [getting started tutorials](docapis_doc_getting_started_section.html). While the getting started tutorial helps beginners get oriented by providing an end-to-end instruction to make a simple API request, the quick reference guide helps users get a glimpse of the system as a whole, often by providing a list of the API's endpoints. * TOC {:toc} @@ -20,23 +20,23 @@ Whether for end-user documentation or developer documentation, the quick referen {% include course_image.html size="large" border="true" filename="nonref_quickreference" ext_print="png" ext_web="svg" alt="Quick reference" caption="Quick reference guides compress the key information into a brief format for easy consumption" %} -The quick reference guide should provide the user with just enough information to get the gist of what the system is about, including the key endpoints and tasks. Often times with APIs, the endpoints have relationships with each other that can be depicted visually. Here's an API diagram I created at a previous company: +The quick reference guide should provide the user with just enough information to get the gist of what the system is about, including the key endpoints and tasks. Often with APIs, the endpoints have relationships with each other that you can depict visually. Here's an API diagram I created at a previous company: {% include course_image.html size="medium" url="https://idratherbewriting.com/learnapidoc/images/sample_api_diagram.pdf" filename="sample_api_diagram.pdf" ext_print="png" ext_web="png" alt="Sample quick reference guide format" caption="A quick reference guide format" %} -The text is Latin filler for privacy reasons, so the logic may not be entirely apparent. But with this API, the endpoints could be organized into different groups. Some of the groups had multiple levels within the endpoint, and multiple include options for each endpoint. I created this diagram in Adobe Illustrator and distributed it as a PDF. Developers found it useful because it tried to make sense of the API as a whole, showing how all the endpoints fit together in a logical harmony. Most commonly with API documentation, the quick reference guide lists abbreviated descriptions of the endpoints. For this reason, the [Swagger UI output](pubapis_swagger_demo.html) can often function as a quick reference guide. +The text is Latin filler for privacy reasons, so the logic may not be entirely apparent. But with this API, the endpoints could be organized into different groups. Some of the groups had multiple levels within the endpoint, and multiple include options for each endpoint. I created this diagram in Adobe Illustrator and distributed it as a PDF. Developers found it useful because it tried to make sense of the API as a whole, showing how all the endpoints fit together in logical harmony. Most commonly with API documentation, the quick reference guide lists abbreviated descriptions of the endpoints. For this reason, the [Swagger UI output](pubapis_swagger_demo.html) can often function as a quick reference guide. Outside of API documentation, quick reference guides tend to focus more on tasks. If you have a service to set up or configure, a more narrative rather than visual format might make sense. Here's a sample layout for such a guide: {% include course_image.html url="images/sample_qrg.png" size="small" filename="quickreferenceguideformat" ext_print="png" ext_web="png" alt="Quick reference guide format focusing on tasks" caption="This quick reference guide format focuses more on tasks than API endpoints" %} -However, with API documentation, usually the quick reference guide focuses on some visual grouping or display of the endpoints, since this is what constitutes the core functionality in an API. +However, with API documentation, usually the quick reference guide focuses on some visual grouping or display of the endpoints since this is what constitutes the core functionality in an API. ## Advantages of distilled information for learning The information in the quick reference usually can’t be single sourced, since it’s not just an excerpt from the docs but rather a more briefly written summary or depiction of the entire system. As a result, many times it seems like yet another deliverable technical writers don’t have time to write. But for the best user experience, the quick reference guide shouldn't be skipped because it provides incalculable value to users. -When you create the quick reference guide, try to condense the most important information into one or two pages that users can print and pin up on their wall. By "condense" I don't mean shrink the font to 6 point, decrease the leading, and eliminate all white space. With the quick reference guide, you take something that's robust and complex, and distill it down to its essence in a way that still maintains clarity to users. +When you create the quick reference guide, try to condense the most important information into one or two pages that users can print and pin up on their wall. By "condense" I don't mean shrink the font to 6-point, decrease the leading, and eliminate all white space. With the quick reference guide, you take something that's robust and complex, and distill it down to its essence in a way that still maintains clarity to users. Through this distillation, quick reference guides provide a unique advantage for users to understand the material. Providing a high-level overview of a system helps users get a sense of the whole before drilling into the details. @@ -61,9 +61,9 @@ The following are sample quick reference guides from various API documentation s {% include course_image.html url="http://api.eventful.com/docs" filename="eventfulquickreference" ext_print="png" ext_web="png" alt="Eventful quick reference guide" caption="Eventful quick reference guide" %} -Eventful provides a one-page quick list of all the endpoints in the API, organized by resource group. Each endpoint is described in about half a line, so you can get a gist of them all quickly. For example, the description for the `/events/get` in their quick reference is "Get an event record." But if you click for more details, the more descriptive definition is "Given an event ID, returns the event data associated with that event. See [http://eventful.com/events/E0-001-000278174-6](http://eventful.com/events/E0-001-000278174-6) for an example interface." +Eventful provides a one-page quick list of all the endpoints in the API, organized by resource group. Each endpoint is described in about half a line, so you can get a gist of them all quickly. For example, the description for the `/events/get` in their quick reference is "Get an event record." But if you click for more details, the more detailed definition is "Given an event ID, returns the event data associated with that event. See [http://eventful.com/events/E0-001-000278174-6](http://eventful.com/events/E0-001-000278174-6) for an example interface." -There's a certain value you get from seeing all the endpoints at a glance. By looking from high-above at the forest, you can see the shape of the forest as a whole. You may not know what kinds of trees the forest contains, but you can comprehend other details that aren't apparent when you're looking at a single tree. +There's a certain understanding you get from seeing all the endpoints at a glance. By looking from high-above at the forest, you can see the shape of the forest as a whole. You may not know what kinds of trees the forest contains, but you can comprehend other details that aren't apparent when you're looking at a single tree. ### Parse @@ -71,7 +71,7 @@ There's a certain value you get from seeing all the endpoints at a glance. By lo The quick reference for Parse is similar to Eventful in that it's a long list of endpoints, this time grouped in tables. Notice that this quick reference page is just a section within one long, single page of docs. In their approach, all documentation is on the same page, but as you scroll down, different entries in the sidebar highlight. -Sometimes developers like the one-page approach because it reduces information fragmentation and lets them use Ctrl+F to find all instances of a keyword. I explored the tradeoffs in this one-page approach in [Single-page docs versus "Click Insanity"](https://idratherbewriting.com/2014/01/12/single-page-docs-versus-click-insanity/). +Sometimes developers like the one-page approach because it reduces information fragmentation and lets them use Ctrl+F to find all instances of a keyword. I explored the tradeoffs in this one-page approach in [Single-page docs versus "Click Insanity."](https://idratherbewriting.com/2014/01/12/single-page-docs-versus-click-insanity/) If you use the [OpenAPI reference docs on GitHub](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md), you'll notice the docs are also contained on a single page. Developers might like to use Ctrl+F to quickly see all instances of a topic. However, I'm not a fan of single-page documentation like this because it provides a lot of visual complexity for users to sort out. @@ -81,7 +81,7 @@ If you use the [OpenAPI reference docs on GitHub](https://github.com/OAI/OpenAPI The Shopify quick reference guide isn't for an API, but it does show the filters, variables, and other functions available in Liquid, which is a scripting language for developers. Here Shopify takes advantage of collapse-and-expand functionality to compress the information. -This quick reference guide is handy because it lets you browse all the available functionality in Liquid at once, so you can know what to dive into for more information. It's like a map of the Liquid terrain. The map let's you know all the functions that exist. +This quick reference guide is handy because it lets you browse all the available functionality in Liquid at once, so you can know what to dive into for more information. It's like a map of the Liquid terrain. The map lets you know all the functions that exist. ## Activity with quick reference guides diff --git a/_docs/documenting_nonreference_content/docapis_glossary_section.md b/_docs/documenting_nonreference_content/docapis_glossary_section.md index a14ca5ed..69005237 100644 --- a/_docs/documenting_nonreference_content/docapis_glossary_section.md +++ b/_docs/documenting_nonreference_content/docapis_glossary_section.md @@ -10,39 +10,39 @@ path1: /docnonref.html no_newsletter: true --- -The API glossary defines all the terms that might be unique to your company or API. Glossaries are often overlooked or skipped, but their importance should not be understated, since much of the user's understanding of API documentation depends on the clarity and alignment of specific terms. +The API glossary defines all the terms that might be unique to your company or API. Glossaries are often overlooked or skipped, but their importance should not be understated since much of the user's understanding of API documentation depends on the clarity and alignment of specific terms. * TOC {:toc} ## Define any words you invest -Unlike most other professional writing disciplines, tech docs are notorious for the amount of specialized terms in their content. Not only do we have unique terms related to our products, industry jargon and company-specific terms make their way into docs, driving up their complexity. +Unlike most other professional writing disciplines, tech docs are notorious for the number of specialized terms in their content. Not only do we have unique terms related to our products, industry jargon and company-specific terms make their way into docs, driving up their complexity. API evangelist Kin Lane recently noted his frustration with an API's language when he encountered an undefined acronym in some API docs he was browsing. Lane explains, > I came across a set of API resources for managing a DEG the other day. You could add, updated, delete and get DEGs. You can also pull analytics, history, and other elements of a DEG. I spent about 10-15 minutes looking around their developer portal, documentation, and even Googling, but never could figure out what a DEG was. Nowhere in their documentation did they ever tell consumers what a DEG was, you just had to be in the know I guess. The API designer (if that occurred) and developer had never stopped to consider that maybe someone would stumble across their very public API and not know what a DEG was. ([Using Plain Language In Your API Paths](https://apievangelist.com/2018/07/09/use-plain-language-in-api-paths/)) -In this case, DEG must have been an acronym specific to the developer's API. In these cases, there's really no excuse for not defining your own pet acronyms and unique vocabulary. +In this case, DEG must have been an acronym specific to the developer's API. In these cases, there's no excuse for not defining your own pet acronyms and unique vocabulary. But many times, acronyms and unfamiliar terms are part of a specialized domain. As a technical writer, using the correct terms for your knowledge domain and your product is necessary, and those terms are often appropriate for that particular knowledge domain. To simplify the language, you can't just omit the necessary terminology for the domain and substitute in more friendly names. You have to teach the user the right language so they can participate in the conversation. One commonsense approach for teaching users how to speak this language involves defining unfamiliar words for the user by way of a glossary. -{% include course_image.html size="medium" border="true" filename="nonref_glossary" ext_print="png" ext_web="svg" alt="Glossary" caption="Glossaries not only provide clarity about terms for users, they also help the writers think more clearly and consistently about the topic" %} +{% include course_image.html size="medium" border="true" filename="nonref_glossary" ext_print="png" ext_web="svg" alt="Glossary" caption="Glossaries not only provide clarity about terms for users but also help the writers think more clearly and consistently about the topic." %} {: .tip} I provide an [API glossary here](api-glossary.html) that defines many terms related to API documentation. If you run into unfamiliar jargon that I don't define in the topic, you can always consult the glossary. ## Should you provide a glossary? -Usually, providing a glossary in your documentation seems like going above and beyond the call of duty. However, simply defining these terms has tremendous benefit for the writer too, not just for the users. Defining terms helps you recognize the special terminology that might be used with your API — terms that you may have become immune to by hearing them so frequently in project meetings. By defining the terms, you ensure that you're using these terms more precisely and accurately (rather than switching around with synonyms for variety). +Usually, providing a glossary in your documentation seems like going above and beyond the call of duty. However, defining these terms has tremendous benefit for the writer too, not just for the users. Defining terms helps you recognize the specialized terminology that might be used with your API — terms that you may have become immune to by hearing them so frequently in project meetings. By defining the terms, you ensure that you're using these terms more precisely and accurately (rather than switching around with synonyms for variety). ## Localization requirements and glossaries If you're planning to localize your API documentation, most translators will require a glossary. Especially with API documentation, there are many technical terms that translators need to to be aware of so they can decide whether the terms should be translated. -For example, suppose in your sample Android app, you have terms like `PlaybackState` and "media session" and "callback" and `BroadcastReceiver`. Translators need to be technical enough to know whether these terms should be translated or left as is. Terms set off in `code` tags normally wouldn't be translated, but many other terms referring to technical elements might also best be left untranslated. It can be a tricky judgement call when the technical term isn't set off as code but refers to a technical concept or class (such as "MediaSession"). +For example, suppose in your sample Android app, you have terms like `PlaybackState` and "media session" and "callback" and `BroadcastReceiver`. Translators need to be technical enough to know whether these terms should be translated or left as is. Terms set off in `code` tags normally wouldn't be translated, but many other terms referring to technical elements might also best be left untranslated. It can be a tricky judgment call when the technical term isn't set off as code but refers to a technical concept or class (such as "MediaSession"). After translators finish translating the content, the translation needs to be checked over by a subject matter expert in that language — usually by a field engineer who works with clients in that locale. The glossary will also assist the subject matter experts who review the translation. @@ -61,7 +61,7 @@ I explored glossaries in depth in [Reducing the complexity of technical language One question to consider is how and where to integrate the glossary definition within your technical content. For example, suppose you have the terms "near field" and "far field" in your content, referring to voice interactions with a device. You might use these terms in a number of sections and different pages. Sure, you could define these terms the first instance in your docs when you use them, but what if they appear on half a dozen pages? Users might not start on the initial page where they're defined. -You could incorporate tooltips (such as these [tooltips from Bootstrap](https://getbootstrap.com/docs/4.1/components/tooltips/)) over the term the first time it's used on each page in your docs. However, on subsequent references, it's probably easiest to link to the glossary definition rather than continually incorporate tooltips. Let users make their own way to the glossary when they need help with a term. If the glossary page is in a clearly visible space, you won't have to go to great lengths to link terms to their glossary definitions with each usage. +You could incorporate tooltips (such as these [tooltips from Bootstrap](https://getbootstrap.com/docs/4.1/components/tooltips/)) over the term the first time it's used on each page in your docs. However, on subsequent references, it's probably easiest to link to the glossary definition rather than continually incorporate tooltips. Let users make their way to the glossary when they need help with a term. If the glossary page is in a clearly visible space, you won't have to go to great lengths to link terms to their glossary definitions with each usage. ## Sample glossary pages @@ -71,7 +71,7 @@ The following are sample glossary pages in various APIs. {% include course_image.html url="https://developer.lyft.com/docs/glossary" filename="glossary_lyft" ext_print="png" ext_web="png" alt="Lyft glossary" caption="Lyft glossary" %} -Lyft's glossary doesn't have a ton of terms (there are about 10), but they're specific to the Lyft API world. You see terms such as "Lyft Line," "Lyft Lux," "Lyft Plus," and so on. I like that the developer documentation takes pains to actually define terms that might normally be used on Marketing and Sales spaces. Whenever a company includes a glossary, it demonstrates a sensitivity the company has toward users. The company doesn't assume that their users understand all the company's special terms and vocabulary. +Lyft's glossary doesn't have a ton of terms (there are about 10), but they're specific to the Lyft API world. You see terms such as "Lyft Line," "Lyft Lux," "Lyft Plus," and so on. I like that the developer documentation takes pains to define terms that might frequently be used on Marketing and Sales spaces. Whenever a company includes a glossary, it demonstrates a sensitivity the company has toward users. The company doesn't assume that their users understand all the company's specialized terms and vocabulary. ### Yext @@ -83,7 +83,7 @@ When viewing the glossary, the terms also appear in the sidebar, replacing any d One challenge this Yext example raises is how to distribute glossaries across multiple doc sets. Suppose only some of these terms are relevant to one doc set, and other terms are relevant to another doc set. Do you partition the glossary into multiple specialized glossaries by product, or just have one general glossary across all products? -Use the strategy that makes sense for your docs. For the most part, since users just jump down to one specific glossary entry, it probably doesn't matter if other terms (that aren't specific to the doc set in context) are also included. On the other hand, filtering the definitions to a relevant subset would also encourage readers to actually browse through the definitions. +Use the strategy that makes sense for your docs. For the most part, since users mostly jump down to one specific glossary entry, it probably doesn't matter if other terms (that aren't specific to the doc set in context) are also included. On the other hand, filtering the definitions to a relevant subset would also encourage readers to browse through the definitions. ### Apigee diff --git a/_docs/documenting_nonreference_content/docapis_nonref_activity.md b/_docs/documenting_nonreference_content/docapis_nonref_activity.md index 81b451bd..c4f1f1d8 100644 --- a/_docs/documenting_nonreference_content/docapis_nonref_activity.md +++ b/_docs/documenting_nonreference_content/docapis_nonref_activity.md @@ -8,6 +8,6 @@ section: docendpoints path1: /docendpoints.html --- -With each of the non-reference topics in this section, you've been analyzing the topic in the context of the [open-source project you identified](docapis_find_open_source_project.html). Now broaden your analysis to see how these non-reference topics appear in other API documentation sites. Remember that sometimes the best way to learn how to create API documentation is to carefully observe how it's done on sites you admire. Following common practices in the industry helps you create more predictable, easy-to-follow patterns in your own documentation. +With each of the non-reference topics in this section, you've been analyzing the topic in the context of the [open-source project you identified](docapis_find_open_source_project.html). Now broaden your analysis to see how these non-reference topics appear in other API documentation sites. Remember that sometimes the best way to learn how to create API documentation is to carefully observe how it's done on sites you admire. Following standard practices in the industry helps you create more predictable, easy-to-follow patterns in your own documentation. {% include content/activities/assess_nonref_content.md %} diff --git a/_docs/documenting_nonreference_content/docapis_sdks_and_sample_apps.md b/_docs/documenting_nonreference_content/docapis_sdks_and_sample_apps.md index 0f574a71..0a3708fc 100644 --- a/_docs/documenting_nonreference_content/docapis_sdks_and_sample_apps.md +++ b/_docs/documenting_nonreference_content/docapis_sdks_and_sample_apps.md @@ -8,14 +8,14 @@ section: docnonref path1: /docnonref.html --- -SDKs (software development kits) and sample apps are similar to [code samples and tutorials](docapis_codesamples_bestpractices.html) but are much more extensive and usually involve a whole collection of files that work together as a package or sample app. The SDK might include libraries that you download and incorporate into your application, and can include tools, sample apps, and other code. +SDKs (software development kits) and sample apps are similar to [code samples and tutorials](docapis_codesamples_bestpractices.html) but are much more extensive and usually involve a whole collection of files that work together as a package or sample app. The SDK might include libraries that you download and incorporate into your application, and can consist of tools, sample apps, and other code. * TOC {:toc} ## What is an SDK? -The terms API and SDK are often used together, but they aren't synonyms. SDKs implement the language-agnostic REST API in a specific language, such as Java or C++. REST APIs by themselves aren't tied to any particular language; usually you demonstrate the APIs by [making calls using cURL](docapis_make_curl_call.html), a command-line tool for submitting web requests and getting responses. But developers won't use cURL requests when they implement your API. Instead, they will implement the API requests using the language their application is coded in. +The terms API and SDK are often used together, but they aren't synonyms. SDKs implement the language-agnostic REST API in a specific language, such as Java or C++. REST APIs by themselves aren't tied to any particular language; usually, you demonstrate the APIs by [making calls using cURL](docapis_make_curl_call.html), a command-line tool for submitting web requests and getting responses. But developers won't use cURL requests when they implement your API. Instead, they will implement the API requests using the language their application is coded in. For example, Python, C++, or Node applications make API requests in different ways. Each language has its own way of constructing requests to a web API. You can use Postman or Paw to auto-generate a simple request in a specific language (see [Auto-generating code samples](docapis_doc_sample_requests.html#auto-generating-code-samples)). However, the SDK takes the implementation to another level. SDKs might involve many more files or libraries as part of the implementation. @@ -33,15 +33,15 @@ Sandoval compares examples from both Facebook APIs and SDKs to clarify the diffe In the SwaggerHub tutorial, I showed how to [auto-generate client SDKs](pubapis_swaggerhub_smartbear.html#auto-generate-client-sdks) through SwaggerHub's interface. But usually rather than relying on auto-generated SDKs, if your development team offers a client SDK, it will be code that the development team prepares and tests. The development team often provides the SDK in a few target languages based on their user's main language, making it easier for users to implement the API. -As an API technical writer, documenting SDKs and sample apps presents a tough challenge because SDKs require you to be familiar with one or more programming languages. I explore the question of [how much code you need to know](jobapis_learning_code.html) in the [Jobs section](jobapis.html), so I won't get into too much detail here. Usually, engineers don't expect you to know multiple programming languages in depth, but some familiarity with them will be required in order to both write and review the documentation. When deciding whether to call a block of code a function, class, method, or other name, you need to have a basic understanding of the terms used in that language. +As an API technical writer, documenting SDKs and sample apps presents a tough challenge because SDKs require you to be familiar with one or more programming languages. I explore the question of [how much code you need to know](jobapis_learning_code.html) in the [Jobs section](jobapis.html), so I won't get into too much detail here. Usually, engineers don't expect you to know multiple programming languages in depth, but some familiarity with them will be required in order to both write and review the documentation. When deciding whether to call a block of code a function, class, method, or another name, you need to have a basic understanding of the terms used in that language. {% include course_image.html size="medium" border="true" filename="nonref_sdksampleapp" ext_print="png" ext_web="svg" alt="SDKs and sample apps" caption="SDKs and sample apps" %} -If you're unfamiliar with the language, you can just take what engineers write, clean it up a bit, try to walk through the steps to get any sample apps working, and see what feedback you get from users. Usually, if you can get a sample app installed and working, and make sure that the basic documentation for running the app works, as well as what the app does, that might be sufficient. But of course making any significant contributions to SDK documentation will require you to be familiar with that programming language. +If you're unfamiliar with the language, you can just take what engineers write, clean it up a bit, try to walk through the steps to get any sample apps working and see what feedback you get from users. Usually, if you can get a sample app installed and working, and make sure that the basic documentation for running the app works, as well as what the app does, that might be sufficient. But of course, making any significant contributions to SDK documentation will require you to be familiar with that programming language. {% include random_ad2.html %} -As I mentioned in the [Code samples and tutorials](docapis_codesamples_bestpractices.html), you don't need to document how a particular language works, just how your own company's SDK works. Presumably, if an engineer downloads the Java SDK for an API, it's because the engineer is already familiar with Java. However, if your API was implemented in a particular way in Java, you should explain *why* that approach was taken. (Granted, understanding the difference between documenting Java and documenting a particular approach in the Java implementation also sort of requires you to [understand Java](nativelibraryapis_java_crash_course.html).) +As I mentioned in the [Code samples and tutorials](docapis_codesamples_bestpractices.html), you don't need to document how a particular language works, just how your own company's SDK works. Presumably, if an engineer downloads the Java SDK for an API, it's because the engineer is already familiar with Java. However, if your API was implemented in a particular way in Java, you should explain *why* that approach was taken. (Granted, understanding the difference between documenting Java and documenting a particular approach in the Java implementation also requires you to [understand Java](nativelibraryapis_java_crash_course.html).) ## Sample SDKs and sample apps @@ -51,7 +51,7 @@ The following examples show documentation for some sample SDKs and sample apps. {% include course_image.html url="https://openweathermap.org/examples" filename="codesamples_openweathermap" ext_print="png" ext_web="png" alt="Code samples for OpenWeatherMap API" caption="Code samples for OpenWeatherMap API" %} -The example integrations for the OpenWeatherMap API aren't just short code snippets that show how to make a request to an endpoint. Instead, they are full-fledged, sophisticated integrations across a variety of platforms. As such, many of the code samples are stored in GitHub. Each scenario has a detailed explanation. +The example integrations for the OpenWeatherMap API aren't just short code snippets that show how to call an endpoint. Instead, they are full-fledged, sophisticated integrations across a variety of platforms. As such, many of the code samples are stored in GitHub. Each scenario has a detailed explanation. If you can put your sample apps and SDKs on GitHub, it's usually a good idea to do so. Storing code on GitHub accomplishes two purposes: First, it usually puts the burden on engineering to maintain and test the code samples as well as respond to issues users might log against the project. Second, it makes it easier to provide fully functional code, since users can clone the project and start working with it immediately. The development team can also push out updates easily. @@ -69,9 +69,9 @@ The SDKs in the [Paypal's Additional information](https://developer.paypal.com/d The Heroku SDK is actually operated by PubNub and includes a Ruby, Java, Node JS, Python, and PHP SDK. If you look at, for example, the [Python SDK documentation](https://devcenter.heroku.com/articles/pubnub#python-sdk-documentation), you see links to Getting Started, Tutorials, and API reference. -As I mentioned earlier, it's unlikely that you'll be able to contribute significantly to either writing or reviewing the SDK documentation unless you're somewhat familiar with the language. Development groups usually don't expect technical writers to be conversant in half a dozen languages. More likely, you'll be reliant on engineers who are conversant in these languages and frameworks to author this content. But doing so will require you to interact skillfully with engineers and be somewhat familiar with programming lingo and concepts. +As I mentioned earlier, it's unlikely that you'll be able to contribute significantly to either writing or reviewing the SDK documentation unless you're somewhat familiar with the language. Development groups usually don't expect technical writers to be conversant in half a dozen languages. More likely, you'll be reliant on engineers who are conversant in these languages and frameworks to author this content. But doing so will require you to interact skillfully with engineers and be somewhat familiar with programming jargon and concepts. -If engineers tell you that users should know X, don't simply submit to their judgment out of ignorance with the language. Instead, find some developers in that language (even internal engineers in other groups) to test the documentation against. If those users push back and say they need more detail, you can then interface with the engineering team to provide it. +If engineers tell you that users should know X, don't just submit to their judgment out of ignorance with the language. Instead, find some developers in that language (even internal engineers in other groups) to test the documentation against. If those users push back and say they need more detail, you can interface with the engineering team to provide it. Without more familiarity with the language of the SDK, technical writers act more as mediators between the engineering authors and the engineering users. Technical writers identify and fill gaps in the documentation, and they often manage the publishing and distribution of the docs. But the content itself might be too technical for most technical writers to play a content authoring role. (I explored this topic in depth in an essay in my Simplifying Complexity series called [Be both a generalist and specialist through your technical acuity](https://idratherbewriting.com/simplifying-complexity/both-a-generalist-and-specialist-through-technical-acuity.html).) @@ -81,9 +81,9 @@ Without more familiarity with the language of the SDK, technical writers act mor One notable characteristic of the AWS docs is their consistency from doc set to doc set. The consistency leads to predictability and hence usability. However, in the SDK docs, you can see that different document generators are used to generate the docs for the various libraries. If you look at the API references for each of these SDK libraries, you'll see a C++ document generator for [C++ SDK docs](http://sdk.amazonaws.com/cpp/api/LATEST/index.html), a Ruby document generator for [Ruby SDK docs](https://docs.aws.amazon.com/sdk-for-ruby/v3/api/index.html), a PHP document generator for [PHP SDK](https://docs.aws.amazon.com/aws-sdk-php/v3/api/), a .NET document generator for [.NET SDK docs](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/Index.html), a Java document generator for [Java SDK docs](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/index.html) and so on. -Each programming language typically has its own annotation syntax and document generation tools. The annotation syntax (which programmers use directly in the code — see [Javadoc tags](nativelibraryapis_javadoc_tags.html) for an example of Javadoc tags) differs by language and tool but is largely similar. Because the documentation is generated from annotations in the code, engineers usually write and maintain this documentation. (Having engineers write and maintain it also reduces documentation drift.) +Each programming language typically has its own unique annotation syntax and document generation tools. The annotation syntax (which programmers use directly in the code — see [Javadoc tags](nativelibraryapis_javadoc_tags.html) for an example of Javadoc tags) differs by language and tool but is mostly similar. Because the documentation is generated from annotations in the code, engineers usually write and maintain this documentation. (Having engineers write and maintain it also reduces documentation drift.) -Even so, there is probably quite a bit of variability from one library to the next. How do engineers ensure they use the same description for a class in Java that they do for Ruby and PHP? These document generator tools aren't usually smart enough to leverage snippets or includes stored in a common online repository. You also can't usually use variables or other single-sourcing techniques. As a result, there might be a lot of variation from one SDK's documentation to another for mostly the same concepts. +Even so, there is probably quite a bit of variability from one library to the next. How do engineers ensure they use the same description for a class in Java that they do for Ruby and PHP? These document generator tools aren't usually smart enough to leverage snippets or includes stored in a shared online repository. You also can't usually use variables or other single-sourcing techniques. As a result, there might be a lot of variation from one SDK's documentation to another for mostly the same concepts. ### Google Cloud SDK @@ -91,14 +91,14 @@ Even so, there is probably quite a bit of variability from one library to the ne The Google Cloud SDK provides quickstart guides for Linux, Debian, Ubuntu, and other operating systems. The guides explain how to install, set up, and manage the SDK commands. An API reference for the commands is also included. -Looking at the Google Cloud SDK versus the Amazon SDK shows some of the breadth and variety of technologies you might have to document in SDK territory. These SDKs are specific to a particular programming language, operating system, or other framework, and as such, it can be daunting to try to ramp up in order to document this category of tools. For SDK documentation, you'll need to work closely with engineers and listen to feedback from users. +Looking at the Google Cloud SDK versus the Amazon SDK shows some of the breadth and variety of technologies you might have to document in SDK territory. These SDKs are specific to a particular programming language, operating system, or another framework, and as such, it can be daunting to try to ramp up to document this category of tools. For SDK documentation, you'll need to work closely with engineers and listen to feedback from users. ## Activity with SDKs With the [open-source project you identified](docapis_find_open_source_project.html), identify the information about any SDKs for the API. Answer the following questions: 1. Does the API project include any SDKs? -2. What language are the SDKs provided in? +2. In what languages are the SDKs provided? 3. Why did the developers choose to make the SDK available in that particular language? 4. How extensive are the instructions for working with that SDK? 5. Where is the code for the SDK stored and delivered? In GitHub? In a separate downloadable zip file? diff --git a/_docs/publishing_api_documentation/pubapis_api_list.md b/_docs/publishing_api_documentation/pubapis_api_list.md index 7f3e9d25..dc40c417 100644 --- a/_docs/publishing_api_documentation/pubapis_api_list.md +++ b/_docs/publishing_api_documentation/pubapis_api_list.md @@ -8,7 +8,7 @@ section: publishingapis path1: /publishingapis.html --- -Rather than approach the topic of publishing prescriptively, lets begin with some concrete examples and move towards the formulation of general principles. The following are more than 100 openly accessible REST APIs that you can browse as a way to look at patterns and examples. You can find many more APIs by browsing [programmableweb.com](http://programmableweb.com). +Rather than approach the topic of publishing prescriptively, let's begin with some concrete examples and move towards the formulation of general principles. The following are more than 100 openly accessible REST APIs that you can browse as a way to look at patterns and examples. You can find many more APIs by browsing [programmableweb.com](http://programmableweb.com). * TOC {:toc} @@ -128,7 +128,7 @@ Browse a few of these documentation sites to get a sense of the variety, but als 108. [Paymill API](https://developers.paymill.com/API/index) 109. [Rundown API](https://rapidapi.com/therundown/api/therundown?endpoint=5ace93eae4b04378c0ca27ba) -{% include tip.html content="I last checked these links in December 2018. Given how fast the technology landscape changes, some links may be out of date. However, if you simply type {product} + api docs into Google's search, you will likely find the company's developer doc site. Most commonly, the API docs are at developer.{company}.com." %} +{% include tip.html content="I last checked these links in December 2018. Given how fast the technology landscape changes, some links may be out of date. However, if you just type {product} + api docs into Google's search, you will likely find the company's developer doc site. Most commonly, the API docs are at developer.{company}.com." %} ## Programmableweb.com: A directory of API doc sites on the open web diff --git a/_docs/publishing_api_documentation/pubapis_design_patterns.md b/_docs/publishing_api_documentation/pubapis_design_patterns.md index 6a360d5f..a8a369a9 100644 --- a/_docs/publishing_api_documentation/pubapis_design_patterns.md +++ b/_docs/publishing_api_documentation/pubapis_design_patterns.md @@ -19,11 +19,11 @@ In the previous topic, we browsed through a long [survey of API doc sites](pubap One overriding commonality with API documentation is that they share a common structure, particularly with the reference documentation around the endpoints. In an earlier section, we explored the common sections in [API endpoint documentation](docendpoints.html). -From a tool perspective, if you have common sections to cover with each endpoint, it makes sense to formalize a template to accommodate the publishing of that content. The template can provide consistency, automate publishing and styles, and allow you to more easily change the design without manually reformatting each section. (Without a template, you could just remember to add the exact same sections on each page, but this requires more effort to be consistent.) With a template, you can insert various values (descriptions, methods, parameters, etc.) into a highly stylized output, complete with sophisticated styling. +From a tool perspective, if you have common sections to cover with each endpoint, it makes sense to formalize a template to accommodate the publishing of that content. The template can provide consistency, automate publishing and styles, and allow you to more easily change the design without manually reformatting each section. (Without a template, you could just remember to add the same sections on each page, but this requires more effort to be consistent.) With a template, you can insert various values (descriptions, methods, parameters, etc.) into a highly stylized output, complete with sophisticated styling. Different authoring tools have different ways of processing templates. With [Jekyll](pubapis_jekyll.html), a static site generator, you can create values in a [YAML file](pubapis_yaml.html) and loop through them using Liquid to access the values. -Here's how you might go about it. In the frontmatter of a page (for example, endpoints.yml), you could list out the key value pairs for each section. +Here's how you might go about it. In the frontmatter of a page (for example, endpoints.yml), you could list out the key-value pairs for each section. ``` resource_name: surfreport @@ -141,7 +141,7 @@ The resulting output was an eye-popping, visually appealing design. To achieve t Although it can be fun to create your own templates (if you like to tinker with doc tools), you can probably already see problems related to custom templates. The templates are entirely arbitrary, with terms and structure based on the designer's perceived needs and styles. If you write documentation to fit a specific template, what happens when you want to switch themes or products? You'd have to create new templates that parse through the same custom frontmatter. It's a lot of custom coding. -Given that REST APIs follow similar characteristics and sections, wouldn't it make sense to create a standard in the way APIs are described, and then leverage tools that parse through these standard descriptions? *Yes!* That's what the OpenAPI specification is all about. Earlier in this course, I explained several [REST API description formats](pubapis_rest_specification_formats.html), and then launched into an extensive tutorial for the [OpenAPI specification](pubapis_openapi_tutorial_overview.html). I provided a tutorial for reading the OpenAPI specification using [Swagger UI](pubapis_swagger.html), along with an activity to [create your own Swagger UI](pubapis_swagger.html#create_swaggerui). +Given that REST APIs follow similar characteristics and sections, wouldn't it make sense to create a standard in the way APIs are described, and then leverage tools that parse through these standard descriptions? *Yes!* That's what the OpenAPI specification is all about. Earlier in this course, I explained several [REST API description formats](pubapis_rest_specification_formats.html) and then launched into an extensive tutorial for the [OpenAPI specification](pubapis_openapi_tutorial_overview.html). I provided a tutorial for reading the OpenAPI specification using [Swagger UI](pubapis_swagger.html), along with an activity to [create your own Swagger UI](pubapis_swagger.html#create_swaggerui). My point here is that you shouldn't be overwhelmed by the coding challenges around creating your own API templates. The Aviator theme shows one custom approach, and I highlight it here with code samples to demonstrate the complexity and custom-nature of defining your own templates. But this isn't the only approach nor is it even the recommended approach. @@ -157,7 +157,7 @@ I hinted at this earlier (in [The market for REST API documentation](docapis_int One of the challenges in using documentation generated from [OpenAPI and Swagger](pubapis_swagger_intro.html) or some other document generation process is figuring out how to integrate it with the rest of the site. Ideally, you want users to have a seamless experience across the entire website. If your endpoints are rendered into their own separate view, how do you integrate the endpoint reference into the rest of the documentation? -If you can integrate the branding and search, users may not care. But if it feels like users are navigating several sites poorly cobbled together, the UX experience will be somewhat fragmented. +If you can integrate the branding and search, users may not care. But if it feels like users are navigating several sites that are poorly cobbled together, the UX experience will be somewhat fragmented. {% include random_ad.html %} @@ -165,11 +165,11 @@ Think about other content that users will interact with, such as marketing conte The reality is that most API documentation sites are custom-designed websites that blend seamlessly with the other marketing content on the site because your API doc must sell your API. As a website platform (rather than a tripane help output), you can leverage all the HTML, CSS, and JS techniques available in building websites. You aren't limited to a small subset of available tools that are allowed by a particular help authoring tool; instead, you have the whole web landscape and toolset at your disposal. -This open invitation to use the tools of the web to construct your API doc site is both a benefit and a challenge. A benefit because, for the most part, there's nothing you can't do with your docs. You're only limited by your lack of knowledge about front-end coding. But it's also a challenge because many of the needs you may have with docs (single sourcing, PDF, variables, and more) might not be readily available with common website tooling. +This open invitation to use the tools of the web to construct your API doc site is both a benefit and a challenge. A benefit because, for the most part, there's nothing you can't do with your docs. You're only limited by your lack of knowledge about front-end coding. But it's also a challenge because many of the needs you may have with docs (single sourcing, PDF, variables, and more) might not be readily available with most website tooling. ## Pattern 3: Abundant code samples {#abundant_code_examples} -More than anything else, developers love [code examples](docapis_codesamples_bestpractices.html), and the abundance of syntax-highlighted, properly formatted code samples on API doc sites constitutes a design pattern. Usually the more code you can add to your documentation, the better. Here's an example from Evernote's API: +More than anything else, developers love [code examples](docapis_codesamples_bestpractices.html), and the abundance of syntax-highlighted, properly formatted code samples on API doc sites constitutes a design pattern. Usually, the more code you can add to your documentation, the better. Here's an example from Evernote's API: Evernote code examples @@ -177,9 +177,9 @@ James Yu at Parse gives the following advice: >Liberally sprinkle real world examples throughout your documentation. No developer will ever complain that there are too many examples. They dramatically reduce the time for developers to understand your product. In fact, we even have example code right on our homepage. ([Designing Great API Docs](https://www.pixelstech.net/article/1331352900-Designing-Great-API-Docs)) -For code samples, you'll want to incorporate syntax highlighting. The syntax highlighter colors different elements of the code sample appropriately based on the programming language. There are numerous syntax highlighters that you can usually incorporate into your platform. For example, Jekyll uses [rouge](https://github.com/jneen/rouge) by default. Another common highlighter is [pygments](http://pygments.org/). These highlighters have stylesheets prepared to highlight languages based on specific syntax. +For code samples, you'll want to incorporate syntax highlighting. The syntax highlighter colors different elements of the code sample appropriately based on the programming language. There are many syntax highlighters that you can usually incorporate into your platform. For example, Jekyll uses [rouge](https://github.com/jneen/rouge) by default. Another common highlighter is [pygments](http://pygments.org/). These highlighters have stylesheets prepared to highlight languages based on specific syntax. -Usually, tools that you use for authoring will incorporate highlighting utilities (based on Ruby or Python) into their HTML generation process. You usually don't implement the syntax highlighter as a standalone tool. If you don't have access to a syntax highlighter for your platform, you can [manually add a highlighting using syntax highlighter library](http://code.tutsplus.com/tutorials/quick-tip-how-to-add-syntax-highlighting-to-any-project--net-21099). +Usually, tools that you use for authoring will incorporate highlighting utilities (based on Ruby or Python) into their HTML generation process. You don't normally implement the syntax highlighter as a standalone tool. If you don't have access to a syntax highlighter for your platform, you can [manually add a highlighting using syntax highlighter library](http://code.tutsplus.com/tutorials/quick-tip-how-to-add-syntax-highlighting-to-any-project--net-21099). Another important element in code samples is to use consistent white space. Use a tool to format the code with the appropriate spacing and line breaks. You'll need to format the code based on the conventions of the programming language. Fortunately, there are many code beautifier tools online to automate that (such as [Code Beautify](https://codebeautify.org/javaviewer)). @@ -193,7 +193,7 @@ For example, here's the [Google JavaScript Style Guide](http://google.github.io/ ## Pattern 4: Lengthy pages {#longish_pages} -One of the most stark differences between regular end-user documentation and developer documentation is that developer doc pages tend to be much longer. Why are the pages longer? In [How API Documentation Fails](https://ieeexplore.ieee.org/document/7140676/) (published in [*IEEE Software*](https://ieeexplore.ieee.org)), Martin Robillard and Gias Uddin looked at common reasons why developers had severe problems with API documentation. In addition to incompleteness, ambiguity, and other reasons, the researchers also found that "fragmentation" was cited as a common issue (which is more related to the presentation of content than the content itself). +One of the starkest differences between regular end-user documentation and developer documentation is that developer doc pages tend to be much longer. Why are the pages longer? In [How API Documentation Fails](https://ieeexplore.ieee.org/document/7140676/) (published in [*IEEE Software*](https://ieeexplore.ieee.org)), Martin Robillard and Gias Uddin looked at common reasons why developers had severe problems with API documentation. In addition to incompleteness, ambiguity, and other reasons, the researchers also found that "fragmentation" was cited as a common issue (which is more related to the presentation of content than the content itself). Robillard and Udin explain: @@ -201,7 +201,7 @@ Robillard and Udin explain: Developers in their survey said they "had difficulty navigating through the myriad pages in an API document to find information," with one respondent explaining: -> I find really difficult to use, where you have to have 10s of clicks through links to find the information you need, and page after page to read. +> Fragmented documentation I find really difficult to use, where you have to have 10s of clicks through links to find the information you need, and page after page to read. If you're using an information model in your documentation that chunks information, make sure your presentation to the user doesn't fragment the content into too many discrete pieces (as I wrote about in [Does DITA Encourage Authors to Fragment Information into a Million Little Pieces?](https://idratherbewriting.com/2013/04/22/does-dita-encourage-authors-to-fragment-information-into-a-million-little-pieces/)). @@ -223,8 +223,8 @@ For another example of a long page, see the Reddit API: Why do API doc sites tend to have such lengthy pages? Here are a few reasons: * **Provides the big picture**: As Yu indicates, single-page docs allow users to zoom out or in depending on the information they need. A new developer might zoom out to get the big picture, learning the base REST path and how to submit calls. But a more advanced developer already familiar with the API might need only to check the parameters allowed for a specific endpoint. The single-page doc model allows developers to jump to the right page and use Ctrl+F to locate the information. -* **Many platforms lack search**: A lot of the API doc sites don't have good search engines. In fact, many lack built-in search features altogether. This is partly because Google does such a better job at search, the in-site search feature of any website is often meager by comparison. Also, some of the other document generator and static site generator tools just don't have search (neither did Javadoc). Without search, you can find information by creating long pages and using Ctrl+F. -* **Everything is at your fingertips**: If the information is chunked up into little pieces here and there, requiring users to click around constantly to find anything (as is [often the case with DITA's information model](https://idratherbewriting.com/2013/04/22/does-dita-encourage-authors-to-fragment-information-into-a-million-little-pieces/)), the experience can be like playing information pinball. As a general strategy, you want to include complete information on a page. If an API resource has several different methods, splitting them out into separate pages can create findability issues. See [Single Page Docs: Stop the Click Insanity](https://www.youtube.com/watch?v=rXcdTYuxwys) by Brandon Philips for more. Sometimes it makes sense to keep all related information in one place, with "everything at your fingertips." This is the approach the authors of the [OpenAPI spec on GitHub](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) took — one massive page, with the ability to use Ctrl+F to easily jump around. +* **Many platforms lack search**: A lot of the API doc sites don't have good search engines. Many lack built-in search features altogether. This is partly because Google does such a better job at search, the in-site search feature of any website is often meager by comparison. Also, some of the other document generator and static site generator tools don't have search (neither did Javadoc). Without search, you can find information by creating long pages and using Ctrl+F. +* **Everything is at your fingertips**: If the information is chunked up into little pieces here and there, requiring users to click around constantly to find anything (as is [often the case with DITA's information model](https://idratherbewriting.com/2013/04/22/does-dita-encourage-authors-to-fragment-information-into-a-million-little-pieces/)), the experience can be like playing information pinball. As a general strategy, you want to include complete information on a page. If an API resource has several different methods, splitting them out into separate pages can create findability issues. See [Single Page Docs: Stop the Click Insanity](https://www.youtube.com/watch?v=rXcdTYuxwys) by Brandon Philips for more. Sometimes it makes sense to keep all related information in one place, with "everything at your fingertips." This is the approach the authors of the [OpenAPI spec on GitHub](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md) took — one endless page, with the ability to use Ctrl+F to jump around easily. * **Today's navigation controls are sophisticated**: Today there are better navigation controls today for moving around on long pages than there were in the past. For example, [Bootstrap's Scrollspy feature](http://getbootstrap.com/docs/4.0/components/scrollspy/) dynamically highlights your place in the sidebar as you're scrolling down the page. Other solutions allow collapsing or expanding of sections to show content only if users need it. Usually the long pages on a site are the reference pages. Personally, I'm not a fan of listing every endpoint on the same long page. Long pages also present challenges with linking as well. However, I do tend to create lengthier pages in API doc sites than I typically see in other types of documentation. @@ -239,13 +239,13 @@ Here's a sample API explorer from [Watson's AlchemyLanguage API](https://watson- -Are API explorers novel, or instructive? If you're going to be making a lot of calls, there's no reason why you couldn't just use [curl](docapis_make_curl_call.html) or [Postman](docapis_postman.html) (particularly the [Postman Run Button](docapis_doc_getting_started_section.html#runinpostmanbutton)) to quickly make the request and see the response. However, the API Explorer embedded directly in your documentation provides more of a graphical user interface that makes the endpoints accessible to more people. You don't have to worry about entering exactly the right syntax in your call — you just have to fill in the blanks. +Are API explorers novel, or instructive? If you're going to be making a lot of calls, there's no reason why you couldn't just use [curl](docapis_make_curl_call.html) or [Postman](docapis_postman.html) (particularly the [Postman Run Button](docapis_doc_getting_started_section.html#runinpostmanbutton)) to quickly make the request and see the response. However, the API Explorer embedded directly in your documentation provides more of a graphical user interface that makes the endpoints accessible to more people. You don't have to worry about entering the right syntax in your call — you just have to fill in the blanks. -However, API Explorers tend to work better with simpler APIs. If your API requires you to retrieve data before you can use a certain endpoint, or if the data you submit is a JSON object in the body of the post, or you have some other complicated interdependency with the endpoints, the API Explorer might not be as helpful. Nevertheless, clearly it is a design pattern to provide this kind of interactivity in API documentation. +However, API Explorers tend to work better with simpler APIs. If your API requires you to retrieve data before you can use a certain endpoint, or if the data you submit is a JSON object in the body of the post, or you have some other complicated interdependency with the endpoints, the API Explorer might not be as helpful. Nevertheless, it is a design pattern to provide this kind of interactivity in API documentation. -If your users log in, you can store their API keys and dynamically populate the calls and code samples with API keys. The API key can most likely be a variable that stores the user's API key. This is a feature provided with sites like [Readme.io](pubapis_headless_cms.html#readmeio). +If your users log in, you can store their API keys and dynamically populate the calls and code samples with API keys. The API key can most likely be a variable that stores the user's API key. This API-key feature is provided with sites like [Readme.io](pubapis_headless_cms.html#readmeio). -However, if you store customer API keys on your site, this might create authentication and login requirements that make your site more complex to create. If your creating this experience in a custom way, you'll probably need the help of a front-end designer and web developer. +However, if you store customer API keys on your site, this might create authentication and login requirements that make your site more complex to create. If you're creating this experience in a custom way, you'll probably need the help of a front-end designer and web developer. ## Some non-patterns in API doc sites diff --git a/_docs/publishing_api_documentation/pubapis_overview.md b/_docs/publishing_api_documentation/pubapis_overview.md index bcfb326a..b1e41fd7 100644 --- a/_docs/publishing_api_documentation/pubapis_overview.md +++ b/_docs/publishing_api_documentation/pubapis_overview.md @@ -37,19 +37,19 @@ The problem is that the very people who can fix this content are usually fully e For example, suppose you identify a high point of developer friction related to poor documentation. Fixing it might not just be a matter of converting the content into plain language or adding some details about missing parameters. The required fixes might involve explaining how the parameters interact in the code, how one value gets used by another and how they get mapped into variables that the code iterates through, etc. Maybe the only person who truly understands the crazy syntax users have to write is the lead developer. -But guess what? What lead developer isn't going to have time to figure out docs. He or she is usually heads-down deep in a complex programming scenario. So the very person who has the knowledge to decompile and excogitate the needed concepts in the documentation usually isn't available to do so. But if the content is beyond the comprehension of generalists, at some point these SMEs will need to devote some time to docs. In these scenarios, Robillard and Uddin say the best help would be to reduce the overhead of the documentation process. +But guess what? What lead developer is going to have time to figure out docs? He or she is usually heads-down deep in a complex programming scenario. So the very person who has the knowledge to decompile and excogitate the needed concepts in the documentation usually isn't available to do so. But if the content is beyond the comprehension of generalists, at some point, these SMEs will need to devote some time to docs. In these scenarios, Robillard and Uddin say the best help would be to reduce the overhead of the documentation process. -As an editor/publisher, you can help the SME author by accurately identifying the point of confusion, the area of the doc that needs updating, and provide easy tools for the SME to make the updates. The engineers can't be bothered to figure out static site generators or publishing workflows, PDFs, or other doc publishing tools. By playing a role as an editor/publisher, you can be a valuable contributor to the product team. This is why being a doc tools expert is particularly relevant in API documentation contexts. +As an editor/publisher, you can help the SME author by accurately identifying the point of confusion, the area of the doc that needs updating, and provide easy tools for the SME to make the updates. The engineers can't be bothered to figure out static site generators or publishing workflows, PDFs, or other doc publishing tools. By playing a role as an editor/publisher, you can be a valuable contributor to the product team. This publishing role is why being a doc tools expert is particularly relevant in API documentation contexts. ## Using tools your SME authors want to use to collaborate {#hats} If engineers and SMEs will be collaborating on some of the doc content, consider using engineering-centric tools rather than writing-centric tools. When I first transitioned to API documentation, I had my mind set on using DITA, and I converted a large portion of my content over to it. -However, as I started looking more at API documentation sites, primarily [those listed on Programmableweb.com](http://www.programmableweb.com/apis/directory), which maintains the largest directory of web APIs, I didn't find many DITA-based API doc sites. In fact, it turns out that almost none of the API doc sites listed on Programmable Web even use traditional tech comm authoring tools. +However, as I started looking more at API documentation sites, primarily [those listed on Programmableweb.com](http://www.programmableweb.com/apis/directory), which maintains the largest directory of web APIs, I didn't find many DITA-based API doc sites. It turns out that almost none of the API doc sites listed on Programmable Web even use traditional tech comm authoring tools. Despite many advances with single sourcing, content re-use, conditional filtering, and other features in help authoring tools and content management systems, almost no API documentation sites (at least those listed on Programmableweb.com) use them. Why is that? Why has the development community implicitly rejected tech comm tools and their many years of evolution? -Granted, there is the occasional HAT, as with [Photobucket's API](http://bit.ly/photobucketlongurl), but they're rare. And it's even more rare to find an API doc site that structures the content in DITA. +Granted, there is the occasional HAT, as with [Photobucket's API](http://bit.ly/photobucketlongurl), but they're rare. And it's even rarer to find an API doc site that structures the content in DITA. The short answer is that in API documentation scenarios, more engineers are writing. The content is so technical, they're the only ones who understand it. And when engineers write, they'll naturally gravitate towards tools and workflows they're familiar with. @@ -65,7 +65,7 @@ If devs are going to contribute to docs (or write docs entirely themselves), the Additionally, almost no HAT runs on a Mac. Many developers and designers prefer Macs because they have a much better development platform (the command line is much friendlier and functional, for example). If you're using a PC, you might struggle to install developer tools or to follow internal tutorials to get set up and test out content. -Even if you could get developers to use a HAT, you'd likely need to buy a license for each contributing developer. In contrast, docs-as-code tools are often open source and can therefore scale across the company without budgetary funding and approval +Even if you could get developers to use a HAT, you'd likely need to buy a license for each contributing developer. In contrast, docs-as-code tools are often open source and can, therefore, scale across the company without budgetary funding and approval. {% include random_ad.html %} @@ -79,21 +79,21 @@ Even for REST APIs, there are tools/libraries that will auto-generate documentat Engineers often want to push the reference documentation for APIs into well-defined templates that accommodate sections such as endpoint parameters, sample requests, sample responses, and so forth. (I discuss these reference sections in [Documenting API endpoints](docendpoints.html).) -If you have a lot of endpoints, you need a system for pushing the content into standard templates. Ideally, you should separate out the various sections (description, parameters, responses, etc.) and then compile the information through your template when you build your site. Or you can use a specification such as [OpenAPI](pubapis_swagger_intro.html) to populate the information into a template. You can also incorporate custom scripts. However, you don't often have these options in HATs, since you're mostly limited to what workflows and templates are supported out of the box. +If you have a lot of endpoints, you need a system for pushing the content into standard templates. Ideally, you should separate the various sections (description, parameters, responses, etc.) and then compile the information through your template when you build your site. Or you can use a specification such as [OpenAPI](pubapis_swagger_intro.html) to populate the information into a template. You can also incorporate custom scripts. However, you don't often have these options in HATs, since you're mostly limited to what workflows and templates are supported out of the box. ### 4. Many APIs have interactive API consoles, allowing you to try out the calls -You won't find an [interactive API console](pubapis_design_patterns.html#interactive_api_explorers) in a HAT. By interactive API console, I mean you enter your own API key and values, and then run the call directly from the web pages in the documentation. ([Flickr's API explorer](https://www.flickr.com/services/api/explore/?method=flickr.photos.search) provides one such example of this interactivity, as does [Swagger UI](pubapis_swagger.html).) The response you see from this explorers is from your own data in the API. +You won't find an [interactive API console](pubapis_design_patterns.html#interactive_api_explorers) in a HAT. By interactive API console, I mean you enter your own API key and values and then run the call directly from the web pages in the documentation. ([Flickr's API explorer](https://www.flickr.com/services/api/explore/?method=flickr.photos.search) provides one such example of this interactivity, as does [Swagger UI](pubapis_swagger.html).) The response you see from this explorers is from your own data in the API. ### 5. With APIs, the doc *is* the product's interface, so it has to be attractive enough to sell the product. -Most output from HATs look dated and old. They look like a relic of the pre-2000 Internet era. (For more on the dated display, see [Tripane help and PDF files: past their prime?](http://www.robertdesprez.com/2013/01/18/tripane-help-and-pdfs-time-to-move-on/) from Robert Desprez.) +Most outputs from HATs look dated and old. They look like a relic of the pre-2000 Internet era. (For more on the dated display, see [Tripane help and PDF files: past their prime?](http://www.robertdesprez.com/2013/01/18/tripane-help-and-pdfs-time-to-move-on/) from Robert Desprez.) For example, here's a sample help output from Flare for the Photobucket API: Publishing API docs -With API documentation, often times the documentation *is* the product's interface — there isn't a separate product GUI (graphical user interface) that clients interact with. Because the product's GUI is the documentation, it has to be sexy and attractive. +With API documentation, often the documentation *is* the product's interface — there isn't a separate product GUI (graphical user interface) that clients interact with. Because the product's GUI is the documentation, it has to be sexy and attractive. Most tripane help doesn't make that cut. If the help looks old and frame-based, it doesn't instill much confidence with developers evaluating it. @@ -103,7 +103,7 @@ In Flare's latest release, you *can* customize the display in pretty significant Based on all of these factors, I decided to put DITA authoring on pause and try a new tool with my documentation: [Jekyll](pubapis_jekyll.html). I've come to love using Jekyll, which allows you to work primarily in Markdown, leverage Liquid for conditional logic, and initiate builds directly from a repository. -I realize that not everyone has the luxury of switching authoring tools, but when I made the switch, my company was a startup, and we had only 3 authors and a minimal amount of legacy content. I wasn't burdened by a ton of documentation debt or heavy processes, so I could innovate. +I realize that not everyone has the luxury of switching authoring tools, but when I made the switch, my company was a startup, and we had only three authors and a minimal amount of legacy content. I wasn't burdened by a ton of documentation debt or cumbersome processes, so I could innovate. Jekyll is just one documentation publishing option in the API doc space. I enjoy working with Jekyll's [code-based approach](pubapis_docs_as_code.html), but there are [many different tools](pubapis_static_site_generators.html) and [publishing options](pubapis_hosting_and_deployment.html) to explore. That's what we'll dive into in this section. diff --git a/_includes/content/activities/api_doc_patterns.md b/_includes/content/activities/api_doc_patterns.md index 6d47aac7..bdd4d903 100644 --- a/_includes/content/activities/api_doc_patterns.md +++ b/_includes/content/activities/api_doc_patterns.md @@ -3,7 +3,7 @@ In this activity, identify common patterns in API documentation sites. 1. Go the list of [100+ API documentation sites](pubapis_apilist.html#list_api_doc_sites). -2. Select about 5 different APIs (choose any of those listed on the page). +2. Select about five different APIs (choose any of those listed on the page). 3. Look for several patterns or commonalities among the API doc sites. For example, you might look for any of the following patterns: * Structure and templates