APIs, maps and apps at stc17

This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. This post is a summary of the session I presented.

My session was titled “A tech writer, a map, and an app”. I told the story of my odyssey into app development, and used my own journey as a way of teaching attendees about apps, APIs, code, maps, open source, and hackathons.

The slides are available on SlideShare: A tech writer, a map, and an app.

We explored some technical details:

• The nuts and bolts of a web-based application like Tech Comm on a Map: where it’s hosted, where the data is stored, the JavaScript code and the APIs that create the map and the app’s functionality.
• How the app’s data is crowd sourced.
• What open sourcing your code means, and why you may want to do it.
• The difference between a web-based application and a mobile app. Tech Comm on a Map is available as a native Android app as well as a webapp.
• The information sources that I used when developing the app.

And we examined how such a project can help develop your soft skills:

• My engineering colleagues helped me kick off the development of the app, and made ongoing suggestions for refinement. The resulting interactions increased mutual understanding and respect.
• Fellow technical writers all over the world help compile the data. A project like this is a good way of connecting with your peers.
• Developing an app can help you better understand your subject and your audience of software engineers and other specialists.
• Such a project gives you confidence in your own abilities, even if you’re just skimming the surface of code complexity.

There’s more about the app on this page: about Tech Comm on a Map.

Thanks to everyone who attended the session!

Webinar on API technical writing with STC India

Are you interested in learning about APIs and API technical writing? Join us for a webinar, hosted by STC India. I’ll demo a couple of APIs and discuss the role of a technical writer in this area of the software industry. We’ll look at examples of API documentation, and discuss what type of documents an app developer expects when using an API.

The title of the webinar is “Introduction to API Technical Writing”. It’s intended for technical writers who know little about APIs (application programming interfaces) and want to explore the field of API technical writing. My hope is that, after attending this webinar, you’ll have the knowledge and tools you need to head off on your own explorations.

APIs (application programming interfaces) make it possible for applications to share information with each other. You could say that APIs are the communication channel of the online world. Developers need help hooking their application up to someone else’s APIs. We, as technical writers, give them that help.

Recording of the webinar [Update on 10 April 2016]: The recording of the webinar is now available on YouTube: Introduction to API Technical Writing.

Registration details: Sign up for the webinar, and read more about it on the STC India site.

Date and time: Friday 18 March 2016, at 1pm Indian time – that’s 6.30pm in Sydney. The session lasts one hour.

Who can join? Anyone. It’s free of charge, and you don’t need to be a member of the STC.

Topic overview:

• An introduction to APIs.
• An overview of the role of API technical writer.
• Our audience – the developers who need our documentation to use APIs in their applications.
• The types of API we might be asked to document.
• Demos of 2 APIs that you can play with yourself.
• What API documentation consists of.
• Examples of good and popular API documentation.
• Working with engineers.
• Tips on getting started as an API technical writer.

Hope to “see” you at the webinar. 🙂

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:

• flickr-net for .NET
• flickgo for Go
• flickrj for Java
• flickcurl for C
• node-flickrapi for Node.js

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

• Twilio API (an impressive number of client libraries)
• Google Calendar API
• Google Maps web services

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?

Fledgling Android app for Tech Comm on a Map

I’m very excited, because there’s an Android app on its way for Tech Comm on a Map. The Android app uses the same data source as the Tech Comm on a Map website – so you can see the same events on the map in both apps. In addition, you can add events to the map directly from within the Android app, and it does smart marker clustering too.

Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. It’s already out there on the Web. See it in action on the Tech Comm on a Map website, and read more on this page.

And now the Android app

The code for the Android app is already on GitHub.  A group of us got together during a hackathon and created the initial version of the app. I’ve added to the app since then, and intend to continue improving it. Eventually I’d like to add it to the Google Play store. There’s a bit to do before that. 🙂

Friendly disclaimer: Although I work at Google, this app is not a Google product. It’s a personal project by me and the other contributors.

The Tech Comm on a Map app for Android is developed with Java and the Android SDK. It uses the following APIs:

• Google Maps Android API
• Google Places API for Android (Autocomplete and Place Picker)
• Google Play services Fused Location Provider (Get Current Location)
• Google Apps Script
• Realm.io (a mobile database)
• AndroidSlidingUpPanel (a draggable sliding-up panel)
• Android Saripaar (a validation library):

If you’re interested in developments, follow the Tech Comm on a Map app for Android on GitHub. You can build it from the source and load it onto your Android device to try it out. It works. 🙂

Introduction to API tech writing – upcoming webinar

On Wednesday February 11th, US EST (that’s Thursday here in Australia), I’m presenting a webinar about API technical writing. It’s the first in a series on API technical writing from the Society for Technical Communication. I’d love it if you could join me online.

The role of API technical writer is exciting, rewarding, and challenging. I’ve been working as a full-time API writer for 18 months now, and I love it!

APIs are a hot topic in our field, and technical writers with the skills to document them are in high demand. Many technical writers are keen to know more about the role, but it can be hard to find information. Sometimes there’s so much information that it’s difficult to know where to start. In presenting this webinar, my aim is to give you a good idea of the role of API technical writer, and some excellent starting points to explore the world of APIs.

Details of the webinar

Title: Introduction to API Technical Writing.
Date and time: Wednesday, 11 February 2015, at 2pm EST (GMT-5) – that’s 6am on Thursday here in Sydney!
Duration: One hour.
Fees and registration/signup: Please refer to the STC announcement: Part 1 in API Series: Introduction to API Technical Writing.

The session covers the following topics:

• What an API is and does.
• Introduction to the role of API technical writer and our audience.
• Overview of the types of developer products we may be asked to document – APIs and others.
• Types of APIs, including REST APIs, other web services, library-based APIs like JavaScript, and more.
• A couple of live demos of APIs that you can play with at home: a JavaScript API and a REST API.
• Examples of good API documentation.
• The components of API documentation, and the technical writer’s role in the creation of each component.
• A day in the life of an API technical writer.
• Tips on getting started in the role.

Here’s a link to the slides on SlideShare: API Technical Writing.

More in the STC’s webinar series on API technical writing

Following on from my introductory webinar, the next two sessions in the STC’s series have already been announced. In episode 2, Ed Marshall talks about documentating Java and C++ APIs. In episode 3, Joe Malin describes how to write effective code samples.

I hope to “see” you at the webinar!