Author Archives: Sarah Maddox

3 essentials in an API get-started guide

Developers may need to hook their application up to an API so that the app can get data from somewhere, or share data with another app, or request a service such as displaying a message to the user. The getting-started guide is one of the most important parts of an API documentation set. Often the developer can find their way around an API with just the getting-started guide and the reference documentation.

A getting-started guide for an API (Application Programming Interface) helps a developer get their application interacting with the API.

At a minimum, a getting-started guide tells developers how to:

  1. Download any tools required, such as an SDK (Software Development Kit) or a code library.
  2. Get any necessary authentication credentials for their app, such as an API key.
  3. Fire up a hello world app. This is a program that does very little. Typically, it prints “hello world” to a web page, a screen, or the developer console. The purpose of a hello world app is to make sure the developer has all the tools and configuration required before they can start developing.

Here are some examples of API getting-started guides:

Interestingly, if you examine API documentation on the Web, you’ll come across a few different types of guides called “getting-started guides” or “quick-start guides”. It’s an overloaded doc type. :) For example, some quick-start guides take the form of a tutorial, leading developers through a simple use case for the API. The resulting app is something more than a hello world app, and is useful for developers who need information about what the API does (typical use cases) as well as the authentication and setup steps.

Top writing tip – go for a walk

You know that feeling when you’ve written yourself into a corner in your blog post, presentation, thesis, or another type of document? Here’s a tip that’s helped me often to get past the corner: Go for a walk!

Take an energetic stroll. In the bush, on the beach, whatever suits you. Don’t consciously think about the problem in your document. If your brain comes up with a thought, toy with that thought in a semi-interested manner. Follow where it goes. Be open to its consequences even if they involve throwing away an entire section of your presentation, redoing some research, changing the direction of your thesis.

The thing is, your subconscious is probably right. Often, it’s bringing to the surface a feeling that you’ve had for a while. That niggling worry that something’s not quite right with the document, but you haven’t had time to go down the rabbit hole of investigation, or are perhaps too timid to follow the White Rabbit to an unknown world of randomly shrinking and expanding presentations. :)

While you’re on the walk, write yourself a note about your musings. Right then and there, in the bush or on the beach. I send myself emails, sometimes a series of them. A note on a scrap of paper would do too. Make sure you capture the actual words of your thoughts, because they encapsulate the insight that you’ve come to.

When you get back to your desk or your computer, save your work in its current state. Then remodel it, based on your new insights.

This happened to me recently. I’d mapped out a presentation then spent weeks working on its separate sections. A couple of days ago I read through a section I’d planned a while ago, which I’d thought would be the centre piece of the presentation. Oh no, it sounds out of place, uninspired, weird even. How can I adapt the rest of the material so this section works?

I went for a walk, watched the birds, admired the budding trees, wrote myself some emails. The end result was that I removed the worrisome section and integrated some of it into the rest of the presentation. The entire concept of the document had developed and moved beyond its erstwhile centre piece.

It’s a bit like those fictional characters who take a story in directions the author hadn’t originally designed.

Top writing tip - go for a walk

I took this picture (above) at Snoqualmie Falls, near Seattle WA.

Excited about tcworld India 2016

I’m delighted that I’ll be attending tcworld India 2016, on 25-26 February in Bangalore. This is an annual conference organised by tekom Europe and TWIN (Technical Writers of India). Let me know if you’re planning to come!

This will be my first trip to India, and of course my first time at tcworld India. I was lucky enough to attend the related tcworld conference in Europe in 2012, where I learned a lot, met many technical writers, and caught up with friends I’d previously met only online. I’m expecting tcworld India to be at least as great. :)

At the moment, I’m having fun putting together my two presentations for the conference. I’ve been invited to give the keynote at the beginning of the conference, which is a huge privilege. In addition, my proposal was accepted to present a session on API technical writing.

Keynote: The future *is* technical communication

Preparing the keynote presentation in particular is a lot of fun. I’m exploring the march of technology, the way we deal with it, and in particular how it’s affecting the way we communicate. Here’s the introduction:

Over the past few years there’s been quite a bit of discussion about the future of technical communication. Now let’s look at the world in a different light:

The future *is* technical communication.

People’s understanding of the world is based on technical communication, and getting more so by the minute… (join me at tcworld India to hear the rest!)

Later presentation: API technical writing

Later in the conference I’ll speak about APIs and API documentation. APIs are a hot topic in our field, and technical writers with the skills to document them are in high demand. Have you ever wondered what API technical writers do and how they go about it? I’ll demonstrate some easy-to-use APIs, examine examples of API documentation, and give some ideas on getting started in this exciting and rewarding area of technical communication.

The conference program for tcworld India 2016 is looking good. I’m looking forward to meeting the speakers, organisers and attendees. And I’m looking forward to exploring Bangalore!

What is an API client library?

Client libraries are sometimes called helper libraries. What are they and how do they help developers use an API?

Over the past year I’ve run a few workshops on API Technical Writing. Part of the workshop content is about client libraries, and I decided it’s worth discussing this topic in a blog post too. It’s of interest to technical writers who are documenting APIs, particularly web services and REST APIs.

What is a client library?

A client library, sometimes called a helper library, is a set of code that application developers can add to their development projects. It provides chunks of code that do the basic things an application needs to do in order to interact with the API. For example, a client library may:

  • Provide boiler-plate code needed to create an HTTP request and to process the HTTP response from the API.
  • Include classes that correspond with the elements or data types that the API expects. For example, a Java client library can return native Java objects in the response from the API.
  • Handle user authentication and authorisation.

How is that useful?

Looking at the developer who’s using the API: With a REST API or any web service API, the developer could be using any of a number of programming languages to make the API calls.

Wouldn’t it be great if we could give them some code in their own language, to help them get started with the API? That’s what a client library does. It helps to reduce the amount of code the application developers have to write, and ensures they’re using the API in the best supported manner.

Examples of client libraries

In some cases, the API developers provide client libraries for the API. In other cases, client libraries are developed and supported by the community rather than the API developer.

For example, here are the Flickr API client libraries listed by programming language, all maintained by the developer community:

Here are more examples of client libraries, listed per API:

Is a client library the same thing as an API?

No, although they’re closely related. My post on API types describes library-based APIs, which are libraries of code that developers need to import before they can use the API. So, how does that differ from a client library?

Here’s how I see the difference between library-based APIs and client libraries:

  • Library-based APIs are those where the developer needs to import or reference a library of code or binary functions before the application can interact with the API. For example, the documentation for the Google Maps JavaScript API describes the HTML <script> element needed to load the API library.
  • Client libraries are additional libraries of code that are provided to make a developer’s life easier and to ensure applications follow best practices when using the API. In general, you can call the API directly without using the client library. (In some cases, though, the client libraries may be the preferred or even the only supported means of interacting with a particular service.)

I’d love to hear your thoughts on this topic – does the above summary make sense, is it useful, and what have I left out?

Inviting Seattle tech comm students to speed networking and workshop

The Puget Sound Chapter of the Society for Technical Communication (STC) is hosting a “speed networking” session at the University of Washington at 6pm on Tuesday, October 20th. I’m delighted to say that I’ll be there too. 

In addition, you’re invited to an API Technical Writing Workshop that I’m running in conjunction with the STC on Friday, October 23rd. It’s open to students as well as people already in the tech writing field. See the details here.

So, that’s 2 tech comm events in one week – an opportunity not to be missed. :)

Quick registration links:

Here’s the poster the STC shared with me, for the speed networking event:

Tech comm networking poster


Random remarks from me:

  • I like the spelling of “alumnae”. At first I thought, “Gah, typo!” Then I realised it’s a thing.
  • The purple colour is awesome. It matches my Ubuntu background!

I hope to meet many students and other Seattle tech comm folks at the networking event and at the workshop!


Get every new post delivered to your Inbox.

Join 1,618 other followers

%d bloggers like this: