---
title: "Recording of STC San Francisco presentation: Beyond mere endpoint reference — the overlooked content in API documentation"
date: 2018-03-08
description: "Slides Audio Event description Beyond mere endpoint reference — the overlooked content in API documentation Slides Here are..."
canonical_url: https://idratherbewriting.com/2018/03/08/stc-sf-preso-nonreference-api-docs/index.html
---

> For AI agents: a documentation index is available at https://idratherbewriting.com/llms.txt. Markdown versions of all pages are available by appending .md to any page URL.

# Recording of STC San Francisco presentation: Beyond mere endpoint reference — the overlooked content in API documentation

> I recently gave a presentation to the STC San Francisco chapter called "Beyond mere endpoint reference — the overlooked content in API documentation" on February 21, 2018. You can browse the slides and listen to the audio recording here.

## Slides

Here are the slides:

[![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/nonrefslides.png)](https://idratherbewriting.com/nonref-content-api-docs/)

## Audio

Here’s the audio:

**Listen here:**

[Audio](https://www.podtrac.com/pts/redirect.mp3/s3.us-west-1.wasabisys.com/idbwmedia.com/podcasts/stcsfpresononref.mp3)

[![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/apple_podcasts.png)](https://itunes.apple.com/us/podcast/id-rather-be-writing-podcast/id277365275) [![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/watchonyoutubeblack.png)](https://www.youtube.com/@idratherbewriting) [![](https://s3.us-west-1.wasabisys.com/idbwmedia.com/images/spotify.png)](https://open.spotify.com/show/4HeOZfPGMMfViOhVS40QBD)

(Note that due to a crash with Camtasia, the screen video didn’t record.)

## Event description

Here’s the presentation description:

> ## Beyond mere endpoint reference — the overlooked content in API documentation
>
> Most discussions about API documentation center on the reference content — the endpoints, parameters, sample requests, and responses, and so on. But actually, the reference docs make up only a fraction of the total documentation related to an API. API documentation also includes how-to topics, tutorials, and other conceptual information. In this presentation, we’ll dive into the non-reference content that is typically found in API documentation. Some of these non-reference sections include the following:
>
> - API Overview
> - Getting started with the API
> - Hello World tutorial
> - Authorization and authentication
> - Status and error codes
> - Rate limiting and thresholds
> - Code samples and tutorials
> - SDK and sample apps
> - Quick reference for the endpoints
>
> Here’s a little more detail of what we’ll cover with these topics:
>
> **How-to topics.** When it comes to documenting common tasks (the how-to topics in documentation), API docs pose unique challenges for technical writers. The common paradigm of providing step-by-step instructions for achieving a goal doesn’t always come so easily with APIs. The endpoints can often be used in innumerable ways and combinations to support a variety of outcomes and purposes. As such, how do you go about creating documentation around specific tasks? When the tasks involve assembling chunks of code, is step-by-step the right approach? In what scenarios would you provide the code up front followed by lengthy explanations or inline comments?
>
> **Hello World tutorials** The Hello World tutorial is one of the most common topics for getting started. But this kind of tutorial varies significantly from the traditional task-based topics in regular documentation. What should a Hello World tutorial cover? What is an acceptable “Time to Hello World?” And how can you accelerate the success of this key tutorial without getting bogged down in lengthy explanations of authorization and configuration?
>
> **Sample apps and SDKs.** Although most APIs are language agnostic, you often provide client SDKs in specific programming languages, such as Java or C++. A single API might have 3-4 SDKs, including implementations for Android and iOS apps. How should technical writers document these sample apps, especially when they’re in programming languages the tech writer doesn’t know? Should you document a sample app with inline code comments?

You can read the event details on the [STC San Francisco site](https://stc-sf.org/).

**Location:**

Workday San Francisco
160 Spear Street, Suite 1700 (between Mission and Howard)
San Francisco, CA 94105

**Time:** 7-8pm