Category Archives: Android API

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

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

Tech Comm on a Map for Android

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:

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. 🙂

Storyboards for video design and review

I’ve just created two short instructional videos, introducing specific aspects of our APIs to developers. I used a storyboard as a way of outlining the video content, illustrating my ideas about the flow of the video, and requesting a review from my colleagues.

A colleague, Rachel, introduced me to the idea of storyboarding a while ago. This is the first time I’ve tried it.

What a storyboard looks like

This is what the storyboard looked like when I sent it out for initial review comments:

My first storyboard

My first storyboard

To get started, I looked at the examples Rachel had given me of her own storyboards, remembering her very useful comments about how she used them. Then I looked online to see what other people are doing. I found two examples that gave me more good ideas on how to represent my video design in a storyboard:

  • Storyboards, from the Advanced Computing Center for the Arts and Design. I like the Hunting Sequence from the Jane Animation Project.
  • Storyboarding, from the UC Berkeley Graduate School of Journalism. The sketches at the bottom of the page are appealing, and show how different formats of storyboard are useful in different situations.

The design of my storyboard is a conglomeration of ideas generated by my colleagues examples and the two sources above. I shared my storyboard template with members of my team, and suggested they may like to use something similar when designing videos. They like the idea, and each person adapted the template to suit them. This approach works surprisingly well.

What a storyboard is good for

For me, the primary goal of a storyboard is to share an easily-absorbed way of representing the flow of the video.

This is what I wrote at the top of my first storyboard:

This storyboard is a precursor to a script. It’s an illustrative way of outlining the video before we start in-depth development of code and script. Note: All visuals are just mockups to give some idea of what’s happening, and are not intended to be the real thing.

Building out the storyboard

As time passed, I fleshed out the script on the storyboard, replacing the outlined content with the words I was planning to say during the presentation. So the storyboard evolved continually during the scripting of the video, the flow design, and the planning of the visual aspects such as screenshots, demonstrations and annotations.

A number of colleagues responded to my requests for review. After a few revisions, my script was ready to move to a separate document for final tweaking and practice runs. This is what the storyboard looked like at that point:

The storyboard ready to be transformed to a script

The storyboard ready to be transformed into a script

The resulting video

This is the very first instructional video that I’ve ever presented! (Apart from videos shot during conference presentations.) It’s short by design. The target audience is developers who are using the Google Maps Android API to include maps in their Android apps.

Producing the video

I could write an entire blog post about the process of filming the video. So for now, I’ll just show you a couple of photos of the video production studio.

The first photo shows me sitting in the hot seat, with the green screen behind me. In the foreground are the two video production screens, with ATEM Television Studio (the input stream switcher) on the right and Wirecast (which we used to define the video format and control the flow) on the left.

In the hot seat in the video production studio

In the hot seat in the video production studio

The second photo is a panoramic view from the hot seat, showing all the lights that glare down at you. The production centre in the middle at the back.

The view from the hot seat

The view from the hot seat

Conclusion

A storyboard is a good tool for solidifying my own ideas about the video, showing them to others, and conducting a collaborative review.

I’d love to hear your ideas about storyboarding, the format of the storyboards you use, and how you find them useful (or not). 🙂

How to write sample code

Technical writers often need to create sample code, to illustrate the primary use case of an API or developer tool, and to help developers get started quickly in the use of the API or tool. Here are some tips on how to go about creating that code. I’ve jotted down everything I can think of. If you have more tips to add, please do. 🙂

I recently published a set of documentation on a utility library created by Chris Broadfoot, a Google developer programs engineer. The utility library is an adjunct to the Google Maps Android API. The documentation includes an overview of all the utilities in the library, a setup guide, and an in-depth guide to one of the utilities. (I’ll document more of the utilities as time goes on.) As part of the guide to the marker clustering utility, I created some sample code that illustrates the most basic usage of the utility and gets developers up and running fast.

Quick introduction to the API and the utility library

The Google Maps Android API is for developers who want to add a map to their Android apps. The API draws its data from the Google Maps database, handles the displaying of the map, and responds to gestures made by the user, such as zooming in and out of the map. You can also call API methods to add markers, rectangles and other polygons, segmented lines (called polylines), images (called ground overlays) and replacement map tiles (called tile overlays). It’s all in the API documentation.

The utility library is an extra set of code that developers can include in their Android apps. It includes a number of useful features that extend the base API. One of those features is “marker clustering”. The full list of features is in the utility library documentation.

The marker clustering utility

The sample code illustrates the marker clustering utility in Chris’s utility library. So before diving into the code, you be asking:

What’s “marker clustering”?

Let’s assume you have a map with a large number of markers. (Typically on a Google Map, a marker is one of those orange pointy droplets that marks a place on the map.) If you display all the markers at once and individually, the map looks ugly and is hard to grok, especially when the map is zoomed out and many markers are concentrated in a small area. One solution is to group neighbouring markers together into a single marker icon (a “cluster”) and then split them into individual marker icons when the user zooms out or clicks on the cluster icon. That’s what Chris‘s marker clustering utility does.

What does marker clustering look like? See the screenshots in the documentation.

Developers can implement the classes Chris has created and customise the appearance and behaviour of the clusters. The utility library also includes a demo app, containing sample implementations of the utilities.

The sample code

The best way to describe a code library is to provide sample code. I created a simple marker clustering example, based on the demo app. Take a look at the sample code in the documentation section on adding a simple marker clusterer.

Now compare it to the code in the demo app that’s part of the utility library: ClusteringDemoActivity.java

The differences, in a nutshell:

  • The sample code doesn’t show any of the “plumbing”, such as the library import statements.
  • The sample code does include a listing of both the primary method that does the clustering (called “setUpClusterer()“) and a class that’s important for developers to understand (“public class MyItem implements ClusterItem“).
  • Instead of reading input from a file, the sample code includes a method called “addItems()” to set up some sample data directly from within the code.
  • I’ve added plentiful comments to the sample code, explaining the bits that are specific to marker clustering or the sample itself.

In summary, the sample code provides all the developer needs to get a simple marker clusterer working, just by copying and pasting the code into an existing Android project.

How to write sample code

While writing the sample code, a thought struck me:

Hey, it’s actually quite an interesting process writing sample code. I’ll blog about what I’m doing here, and see what other technical writers have to say about it. 🙂

First, a stab at defining the goals for the sample code:

  • Get the developer up and running as quickly as possible.
  • Be suitable for copying and pasting.
  • Work (do what it’s meant to do) when dropped into a development project.
  • Be as simple as clear as possible.
  • Provide information that is not easy to find by reading the code.
  • Illustrate the primary, basic use case of the API or tool.

And here are my jottings on how to go about creating a useful code sample:

  • Find out what the primary and simplest use case is. That is what your code should illustrate. Talk to the engineers and product managers, read the requirements or design document, read the code comments.
  • Find out what you can safely assume about your audience. Can you assume they are familiar with the technology you’re working with (in my case, Java and Android development)? Do you know which development tools they are using?
  • Find some “real” code that does something similar to what you need. Perhaps a similar function or a working implementation that’s too complex for your needs.
  • Simplify it. Make names more meaningful. Remove functionality that’s unique to your environment or that adds super-duper but superfluous features. Remove plumbing such as import statements and all but the essential error handling.
  • Put your into a framework and test it. The framework should be one that your audience will be using. In my case, that’s an Android development project.
  • Take screenshots of the code in action. They’re often useful to give people an idea of the goal of the sample code, and of what the API or tool can do.
  • Get the code reviewed.
  • Include it in the doc.
  • If possible, put the code in a source repository and hook it up to some automated tests, to help ensure it will remain current.
  • As far as possible, have all the necessary code in one piece, so that people can copy and paste easily. This may mean moving stuff around.
  • Add code comments. Engineers often add technical comments to the code, but don’t include an introduction or conceptual overview of what’s going on. And our target audience, developers, will often read code comments where they don’t read other docs. So code comments are a great medium for technical communication!

Perhaps the most important thing to do is to see yourself as the advocate for or representative of those developers who need to use the API or tool you’re illustrating. Think what questions they would ask if they had access to the people and tools that you do, and put the answers into the documentation and sample code.

Conclusion

To do this job, tech writers need a certain level of coding knowledge, and also a good understanding of what a developer needs to get started. The sample code provides a stepping stone between the conceptual overviews and the complex implementations.

Well, that’s all I can think of. What have I forgotten? 🙂

%d bloggers like this: