Blog Archives

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!

Hobbies and pastimes of technical writers everywhere

Hallo fellow techcomm folks! Do you have a hobby?

Mine is fairly pedestrian. I like to go walking in the bush. It blows away the cobwebs. Well, actually, I often have to blow away the cobwebs myself. They festoon the pathways in the early morning. It’s best to keep your mouth closed when strolling in the Australian bush, or you’ll find yourself spitting spiders.

Hobbies of technical writers

Sometimes a bird pops out and does something interesting, and I blog about it.

Of a dark winter’s eve I can perchance be found tickling the ivories. Perhaps significantly, other members of the household are usually to be found in the furthest corners of the house.

So fess up

What do you get up to when the pleasures of the pen pall? (Aside from avoiding sentences like that.)

For years I had a Calvin and Hobbes cartoon pasted above my desk. It showed Calvin’s father with a mangled bicycle, obviously the result of a bad stack. The caption read: “The secret to enjoying your job is to have a hobby that’s even worse.”

Documentation that developers need to do their jobs

A fellow technical writer asked me this week about the documentation that developers need to do their jobs. He was thinking not of the guides people need when they want to integrate their systems with another organisation’s systems, but rather the internal guides developers may write for themselves about their projects and tools.

That’s a very good question. I’ve thought about it over the last couple of days, and pulled together a list of the types of developer-focused documentation I’ve come across. If you have any to add, please do!

The list is confined to documents relating to the role of software engineer/developer. It doesn’t include more general information that all employees need, such as human resources and facilities.

Information about the project and system they’re working on

  • Who the people are: engineering team members, product managers, technical writers, stakeholders.
  • Customers: Who they are and what they do, or would like to do, with the system or application that the team is developing.
  • Goals: Mission, vision, goals for the upcoming month/quarter/year.
  • Product requirements document for the system, application, or major feature that they’re working on.
  • Design documents.
  • Architectural overview, preferably in the form of a diagram.
  • Comments in the code, written by their fellow developers.

Help with their development environment

  • How to set  up the development environment for the application/system that the team is developing.
  • Guides to specific tools, whether built in-house or third party, including the IDE of choice, build tool, source repository.
  • A pointer to the issue tracker used by the team.
  • Guide to the team’s code review tool and procedures.
  • Best practices for writing automated tests, and information about existing code coverage.
  • Links to the team’s online chat room, useful email groups, and other communication tools used by the team.
  • Where to go with technical and tooling problems.

Coding guides

  • Coding style guides for each programming language in use.
  • Guidelines for in-code comments: style; where to put them; how long they should be; the difference between simple comments and those that are intended for automated doc generation such as Javadoc; and encouragement that comments in the code are a Good Thing.
  • Best practices for code readability.

Sundry useful guides

  • Communication guidelines, if the developer’s role will involve significant liaison with third-party developers, customers, or important stakeholders.
  • A map to the nearest coffee machine, preferably reinforced by a path of glowing floor lights.

Too much information can be a bad thing. :) I spotted this sign on a recent trip to Arizona:

Too Much Information

Tech Comm on a Map now includes businesses and groups

A month ago I announced my project called “Tech Comm on a Map”. The idea is to help us see what’s happening in the world of technical communication around the globeTech Comm on a Map puts tech comm titbits onto an interactive map, together with the data and functionality provided by Google Maps.

When first announced, the map included data types for conferences, societies, and a grab-bag called “other“, which currently contains a couple of historically-interesting morsels.

Now I’ve added two more data types:

  • businesses for commercial organisations specialising in tech comm, such as consultancies, recruiters, publishers, independent technical writers, and so on.
  • groups for smaller groups and regular meetups of technical communicators, either as part of a larger society/association, or as an independent group.

Any groups or businesses to add?

At this point there are very few businesses and groups on the map. Do you have one you’d like me to add? Please add a comment to this post, including the following information for each item. The information will be publicly available on the map, via an information box that appears when someone clicks on the relevant circle on the map:

  • Type: Conference, Society, Business, or Group
  • Name of the business, group, society or conference.
  • Description.
  • Website address (or an email address that people can use to get more information).
  • Street address (this is essential, to position the item on the map).
  • Start and end date for conferences, or meetup timing for groups (e.g. “First Wednesday of every month at lunch time”, or “Every Tuesday at 7pm”).

Note: Don’t add the names or addresses of any individuals, unless it’s your own name and address. We need to ensure we have people’s permission before adding their information in a comment on this post, or on the map. Any information you add here should be already publicly available on an organisation’s website or other publication.

Contributors to the project

Thanks to the following people who have helped me add data to the map so far: Sarah O’Keefe, Ellis Pratt, Stefan Eike.

Thanks also to Stefan Eike and Stephen Farrar, who have both contributed to the code on GitHub.

More coming

Excited? I am. :) If you’d like to know more about the project, check out the introductory blog post. Soon I’ll write another post with the technical details of the APIs and other tools involved. In the meantime, here’s Tech Comm on a Map.

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,460 other followers

%d bloggers like this: