Blog Archives

Report from Write the Docs Sydney, March meetup

We held the second Write the Docs meetup in Sydney on 2 March. The presentations were on moving into API technical writing, and the story of the Corilla documentation platform.

There was a good crowd at this meetup – around 20 technical writers descended on the Campaign Monitor offices in central Sydney. We were treated to a breath-taking 360-degree panorama of Sydney from the 38th floor of the building, and a couple of entertaining, informative, very different talks.

The recording of the session includes both talks, and is available on YouTube:

Presentation 1: Transitioning into API Tech Writing

The first presentation was from Priya Varghese, a technical writer at Google. Her talk was titled Transitioning into API Tech Writing. A year ago, Priya started work at Google as an API technical writer. Before that, she had many years’ experience as a tech writer for other audiences in the medical, security and education industries.

Priya talked about the questions she had before embarking on this new role, such as: How different is it from tech writing for other audiences? Do I know enough to explain APIs to developers? What if I don’t know how to code? Can API tech writing be fun? Her presentation gives an overview of APIs and the developer audience, the role of an API tech writer, the things you need to know, and the skills you need to acquire. One thing Priya strongly recommends is a mentor, and she finishes her talk by wondering if we should develop mentorship programs to guide and instruct technical writers.

Presentation 2: The Corilla Story

David Ryan, co-founder of Corilla, told the story of the development of Corilla and the forming of a startup. Corilla is an online documentation platform for technical writers, providing documentation authoring, publication and version-control tools. David’s talk was fun and educational, with intriguing glimpses of the roller-coaster ride of a startup founder.

David described how he and his team had the original idea for a new tool while working with a set of tools that was bloated, clumsy, and not designed for technical writing. Their new tool quickly became popular at Red Hat, where David was working at the time. With Red Hat’s blessing, he and his colleague branched out to form their own startup. And the rest is history. Two years later, Corilla is an alumni of the NUMA accelerator in Paris and has customers in more than 80 countries. Watch the video to hear David talk about the journey from then to now.

Advertisements

How a developer accesses an API

This post is one in my emerging series of API basics from a technical writer’s point of view. How does a developer get hold of an API, so that she can use it in her application?

The other day, I was chatting to folks in our Marketing team about the three essential items of information an API quick-start guide should give developers:

  • Where to download the API and other tools you need.
  • Where to get your API key or other required app credentials.
  • A hello world app or some basic sample code.

During that discussion, I realised that the first item (“download the API”) differs depending on the type of API you’re discussing. It’s not always a case of downloading the API and adding it to your development project. Sometimes you don’t need to download anything – you just send a request. Sometimes the download happens each time your application needs to use the API. And sometimes you download something in your development environment and compile it into your application project.

Before the recent discussion, I’d understood the difference subconsciously, but during the conversation it became clear to me that this is something worth bringing to the fore, especially for those of us who need to document or market APIs. It’s a useful way of becoming more familiar with the types of API that we’re writing about. (If you’d like to know more about the various types of API, take a look at my attempt at a tech writer’s classification of APIs.)

Calling a REST API or other web service API

As a developer using a REST API or other web service API, you don’t necessarily need to download anything. You can simply start sending requests over HTTP and receiving responses from the API, which does all the work on the server (“server side”). In some cases, however, the API developer or the development community supplies client libraries that developers can download to provide the basis for their app’s interactions with the API. Examples are the Flickr client library for .NET, the Twilio client libraries, and the client libraries for the Google Maps web services.

Importing a library-based API

For a library-based API, you need to import a library of code or binary functions into your development project (your application). Then you can use the functions and objects in your code. When using a JavaScript API, for example, you get the API by including a <script> element in your HTML page. The <script> element loads the library supplied by the API. In this case, the download of the API happens every time the browser loads the HTML page. This type of API is sometimes referred to as “client side”, because it runs in the browser on the user’s computer. To see an example, take a look at the documentation for the Google Maps JavaScript API, which describes the <script> element needed to load the API library.

For an Android API, you install the Android SDK and then add any additional SDK packages into your development project, within your IDE. (An IDE is an integrated development environment, such as Eclipse or IntelliJ IDEA.) In this case, the API download happens when the developer builds their application. See the Android documentation on installing the SDK and additional packages. The Google Maps Android API, for example, is one of a number of APIs distributed via the Google Play Services SDK, which is one of the packages described in the above link.

Downloading a flower

Recently encountered in my neighbourhood: This sulphur-crested cockatoo is importing a flower recently downloaded from a bottlebrush tree. 🙂

How a developer accesses an API

%d bloggers like this: