Blog Archives

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!

Seattle workshop on API Technical Writing

Will you be in Seattle on Friday, October 23rd? Join me and the Puget Sound Chapter of the STC for a full-day workshop on API technical writing. It’s free, and there’s free food too. :) Join me and other Google tech writers in a day of API doc lectures and hands-on sessions.

Anyone interested in learning about API technical writing is welcome to attend – you don’t need to be a member of the STC.

Quick links: Register to attend, and learn more on the STC Puget Sound site.

What is API technical writing?

API stands for Application Programming Interface. Developers use APIs to make apps that communicate with other apps and software/hardware components. API technical writers create documentation and other content that helps developers hook their apps up to someone else’s API.

For a tech writer, it’s an exciting, challenging and rewarding field. I love it!

This workshop gives you hands-on experience with APIs and API documentation, insight into the demands of the role, and plenty of information for your own follow-up study.

Workshop details

Date: Friday, October 23rd, 2015
Time: 9am to 4pm – breakfast and setup are at 9am, for a start at 9:30 sharp
Instructor: Sarah Maddox  – that’s me ;)
Cost: None. The workshop is given free of charge.
Location: Google Offices, 601 N 34th Street, Seattle, WA 98103. (Link on Google Maps.)

This is a practical course on API technical writing, consisting of lectures interspersed with hands-on sessions where you’ll apply what you’ve learned. The focus is on APIs themselves as well as on documentation, since we need to be able to understand and use a product before we can document it.

The workshop includes the following sessions:

  • Lecture: Introduction to APIs, including a demo of some REST and JavaScript APIs.
  • Hands-on: Play with a REST API.
  • Lecture: JavaScript essentials.
  • Hands-on: Play with a JavaScript API.
  • Lecture: The components of API documentation and other developer aids.
  • Hands-on: Generate reference documentation using Javadoc.
  • Lecture: Beyond Javadoc – other doc generation tools.
  • Lecture: Working with an engineering team

Preparation for the workshop

Please take a look at the prerequisites and setup to see what you need to install on your laptop before the workshop. Doing the recommended installations will save you a lot of time at the workshop so that you can avoid missing crucial bits when you’re there.

Meet Google tech writers

There’ll be some Google tech writers at the workshop, assisting with any difficulties during the hands-on sessions. I’m hoping a couple of them will present some of the lectures too.

Hope to see you there!

Here’s that signup link on Eventbrite. I hope to see you there!

Slide from lecture – working with an engineering team:

Working with an Engineering Team

A technical writer’s mission statement

I recently saw a thought-provoking article on cognitive overhead. It got me thinking about what we do as technical writers.

People learn by attaching a new idea to their existing context. The ability to help them do that is our killer skill. That’s the basis of the tutorials we write, for example: start from a known point and expand the reader’s knowledge.

Based on the above premise, here’s an idea for a technical writer’s mission statement:

Make complex goals achievable within our customer’s context

Originally I’d written “Make complex goals achievable within our reader’s context”. Then I thought the word “reader” may be too narrow, as we often create material in media other than the written word. Actually, that’s often the argument used for calling ourselves “technical communicators” rather than “technical writers”. But that’s another story. :) Anyway, I’m still leaning towards the earlier version of the mission statement:

Make complex goals achievable within our reader’s context

What do you think of these ideas for a mission statement?

After writing this article, I searched to see what other people have said on this topic. Here are some good posts:



Get every new post delivered to your Inbox.

Join 1,618 other followers

%d bloggers like this: