Blog Archives

Talking about APIs and Maps at STC Summit 2017

I’m excited to be speaking soon at STC Summit 2017, the annual conference of the Society for Technical Communication. The event happens in Washington, DC, on 7-10 May. My presentation is about APIs, maps, developers, and a tech writer’s foray into the world of app development.

The conference theme is “gaining the edge”. So I decided to talk about my experiences developing an app, and why I tried my hand at app development. The app, Tech Comm on a Map, is an interactive web-based map that shows events of interest to technical communicators.

In this presentation, you’ll see some code and understand the nuts and bolts of the app – where the data is stored, how it gets there, how it ends up on a map for everyone to see.

Follow me on a tech writer’s odyssey into app development.
Tread in dangerous territory.
We may even see a dragon or two.
Emerge a little triumphant, and certainly well travelled.

Q: Why does the journey on this map start in Sydney and end up on the east coast of the US?
A: Because that’s the trip I’ll make to give this presentation at STC Summit. 🙂

At this session, you’ll learn the 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.

You’ll also see 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.

Here’s the session on the STC Summit schedule: A tech writer, a map, and an app.

You can also read more about the app, Tech Comm on a Map.

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

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.

Introduction to 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!

Follow-up on yesterday’s talk about API technical writing

Yesterday I was privileged and delighted to speak at a meeting of the STC Silicon Valley Chapter in Santa Clara. Thanks so much to Tom Johnson and David Hovey for organising the meeting, and thank you too to all the attendees. It was a lovely experience, with a warm, enthusiastic and inspiring audience. This post includes some links for people who’d like to continue playing with the APIs we saw last night and delving deeper into the world of API documentation.

The presentation is on SlideShare: API Technical Writing: What, Why and How. (Note that last night’s presentation didn’t include slide 51.) The slides include a number of links to further information.

The presentation is a technical writer’s introduction to APIs (Application Programming Interfaces) and to the world of API documentation. I hope it’s useful to writers who’ve had very little exposure to APIs, as well as to those who’ve played with APIs a bit and want to learn about the life of an API technical writer.

Overview

Here’s a summary of the presentation:

  • Introduction to the role of API technical writer.
  • Overview of the types of developer products we may be asked to document, including APIs (application programming interfaces), SDKs (software development kits), and other developer frameworks.
  • What an API is and who uses them.
  • Examples of APIs that are easy to play with: Flickr, Google Maps JavaScript API
  • Types of API (including Web APIs like REST or SOAP, and library-based APIs like JavaScript or Java classes).
  • A day in the life of an API technical writer—what we do, in detail.
  • Examples of good and popular API documentation.
  • The components of API documentation.
  • Useful tools.
  • How to become an API tech writer—tips on getting started.

Demo of the Flickr API

During the session, I did a live demo of the Flickr API. If you’d like to play with this API yourself, take a look at the Flickr Developer Guide (and later the Flickr API reference documentation). You’ll need a Flickr API key, which is quick and easy to get. Slide 23 in my presentation shows the URL for a simple request to the Flickr API.

Demo of the Google Maps JavaScript API

My second demo showed an interactive Google map, embedded into a web page with just a few lines of HTML, CSS and JavaScript. I used the Google Maps JavaScript API. If you’d like to try it yourself, follow the getting started guide in Google’s documentation. You’re welcome to start by copying my code. It’s on Bitbucket: HelloMaps.HTML. That code is what you’ll find on slide 28 in the presentation.

More links

There are more links to follow in the presentation itself: API Technical Writing: What, Why and How. I hope you enjoy playing with some APIs and learning about the life of an API technical writer!

STC Summit 2014 wrapup (stc14)

This week I attended STC Summit 2014, the annual conference of the Society for Technical Communication. This year the conference took place in Phoenix, Arizona. The temperature was 40 degrees Centigrade (over 100 F) when I arrived. Phew!

Hot temps outside, hot topics inside. The conference started with two days of workshops, followed by three days of lectures and learning sessions. There were 7 time slots each day, with as many as 20 tracks running simultaneously. So, plenty of sessions to attend, plenty of topics to take in, and plenty of people to meet. I feel as if I haven’t stopped moving since I touched down in Phoenix on Sunday morning.

The sessions

I blogged about most of the sessions I attended. There were two more where it was just not practical to take notes. One was a series of 5-minute lightning talks, very entertaining, but too fast to do justice with notes. The other session took place just before my own, and I was very busy trying to still my nerves and get in the zone, so I didn’t even try to take notes.

Here are my write-ups, in reverse chronological order:

For a full list of sessions, visit the conference site on Lanyrd.

Any more write-ups?

The STC’s Notebook has some information about the conference, as well as about the STC in general.

If you spot any more posts about the conference, please would you add a comment to this post? I’d love to read them.

Thanks and kudos

A huge vote of thanks to the STC Summit committee and all the people who took part in making this such a great event. From my viewpoint as speaker and attendee, the organisation was flawless. The Phoenix Chapter of the STC  put on a big welcome, and put in a huge amount of work behind the scenes to make everything flow smoothly. It was a lovely experience from start to finish.

Thanks also to all the speakers, who put so much work into their presentations. And to the attendees, without whom the conference would be so much the poorer. It was a great pleasure to meet old acquaintances and to make so many new ones too.

I took this photo in the Desert Botanical Gardens in Phoenix:

Desert Botanical Garden in Phoenix

%d bloggers like this: