Category Archives: STC

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!

Workshop on API technical writing

I’m excited and delighted to announce that I’ll be presenting a one-day workshop on API technical writing, in conjunction with the Silicon Valley Chapter of the STC (Society for Technical Communication). 

The workshop will be 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 will be on APIs themselves as well as on documentation, since technical writers need to be able to understand and use a product before we can document it.

Date: Friday, January 23rd, 2015

Time: 9 am to 4 pm

Location: 1295 Charleston Rd, Mountain View, CA 94043 (Google Maps: https://goo.gl/maps/yW1hu). The building is on the Google campus. The workshop takes place in the “Araujo Tech Talk” room on level 1.

Cost: None. The course is given free of charge, sponsored by Google and the STC Silicon Valley Chapter.

Notes:

  • STC membership is not required.
  • The course is currently fully subscribed. But it’s worth adding your name to the waiting list, in case a place becomes available closer to the date. We’ll check the number of tickets and the waiting list early in January.
  • If you’ve registered but later find you’re unable to attend, you can cancel your order in EventBrite. This will open up a place for people who are on the waiting list.

Workshop description

The course will include the following sessions:

  • Lecture: Introduction to APIs, including a demo of some REST and JavaScript APIs.
  • Hands-on: Play with a REST API and a JavaScript API.
  • Lecture: JavaScript essentials.
  • Hands-on: Use JavaScript to exercise the sample JavaScript API in a more in-depth manner.
  • Lecture: The components of API documentation.
  • Hands-on: Generate reference documentation using Javadoc.
  • Lecture: Beyond Javadoc – other doc generation tools.

Details and signup

For details of food, what to bring, prerequisites, and how to sign up via EventBrite, please head on over to the STC Silicon Valley workshop page.

Parking

Here’s some information about parking near 1295 Charleston Rd, Mountain View (Google Maps: https://goo.gl/maps/yW1hu):

  • There are several parking lots next to building 1295. You can park in any unmarked spot. Avoid spots that are marked for expectant mothers or other special requirements.
  • If parking immediately near building 1295 is full, you can park in the lots near building SB50 (1350 Shorebird Way):
    Parking-Googleplex
  • You can also make use of the valet parking between 1245 & 1225 Charleston Rd.

Questions and comments

Please let me know if you have any questions or comments.

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

7 Archetypes of Video Storytelling (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

This session promises to offer The Content Wrangler at his best: Scott Abel on “The Power of Emotion: The Seven Archetypes of Video Storytelling”.

From Scott:

We’re wired for stories. Human beings are designed to consume stories. It’s how we understand things.

Stories are an art form. They’re often performed, and it’s the emotion in the story that makes us remember them.

Seven recurring themes

Scott showed us examples videos that harness the 7 recurring themes or story archetypes:

  1. Overcoming the monster. David and Goliath, good versus evil, nature versus machine.
  2. The rebirth, revival, renaissance.
  3. The question. A mission to change things for the better.
  4. The journey, or the return. Moving from one idea to another, or growth.
  5. Rags to riches. Overcoming adversity or poverty.
  6. Tragedy. An unhappy ending, or a twist that you don’t expect, almost always involving the main character.
  7. Comedy. Humour, sometimes with a little satire.

We also saw a cute hybrid: a musical comedy

Transmedia

Scott says we need to think about how we’re going to tell stories in our new world of interconnectedness. Send out our message on all channels – the omni-channel approach.

See the retelling of Cinderella in the video below: “Transmedia Storytelling” – liquid content that’s adaptable for distributing to different media. A different way of telling stories altogether.

Cinderella 2.0: Transmedia Storytelling

Don’t be afraid to use emotion to engage your audience!

Thanks Scott

This was a cute, amusing and engaging session. :)

Follow

Get every new post delivered to your Inbox.

Join 1,589 other followers

%d bloggers like this: