01. Sarah Maddox: API Technical Writing (September 21, 2015)

Sarah Maddox presents:

API Technical Writing

sponsored by Google

Sarah Maddox

On Monday, September 21, 2015, learn about API technical writing, apply what you've learned in hands-on sessions, and network with colleagues.

API Technical Writing

9:00 am - 9:30 am EDT (UTC -4) - Breakfast and setup

9:30 am - 4:00 pm EDT (UTC -4) - Workshop presentation with lunch and afternon refreshments

We will provide breakfast, lunch, and afternoon refreshments, free of charge.

API stands for Application Programming Interface. Software developers use APIs to make apps that communicate with other apps and with 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 technical writer, it’s an exciting, challenging and rewarding field.

This is a practical workshop on API technical writing, consisting of lectures interspersed with hands-on sessions where participants will apply what they have learned. The focus is on APIs themselves as well as on documentation, since technical writers need to be able to understand and use a product before they 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

For questions about the workshop content, contact Sarah Maddox on sarahmaddox@google.com.

What to Bring

Bring your own laptop with a WiFi connection and power cable.

Please install and configure the following software before the workshop (see Pre-workshop Software Installation & Configuration below):

    1. Java JDK

    2. A text editor of your choice

    3. Eclipse

    4. Chrome

Audience and Prerequisites

This workshop assumes that you have some experience as a technical writer in the software industry, and are interested in moving into API documentation.

You’ll need a working knowledge of web pages and HTML. It will be useful if you have a basic understanding of programming. Recommended reading before the workshop is:

LOCATION

You cannot walk in.

To register for this event, go to the Register section below and sign up in advance of the registration deadline.

Google (map)

76 9 Av x W 16 St

New York, NY 10011

Enter through the tenant entrance at the corner of W 16 St and 9 Av. Check in at the workshop registration table with Google-branded linen.

Transit (map):

- A,C,E to 14 St

- L to 8 Av

- 1 to 18 St

Day of event contact: +1.9177535954

About Sarah Maddox

Sarah Maddox is a technical writer in Google’s Developer Platforms team, writing the documentation for the Google Maps APIs and the Google Places APIs. She’s also worked at Atlassian and other organizations around the world. With fifteen years’ experience as a technical writer and ten as a software developer, Sarah specializes in making words and code play nicely together. She also has a strong belief that chocolate solves many a tech comm problem.

Blog: ffeathers.wordpress.com

Twitter: @sarahmaddox

Google+: +sarahmaddox

Pre-workshop Software Installation & Configuration

1. Java JDK

You’ll need a recent version of the Java SE JDK. Version 7 and 8 are both fine. Make sure you have the JDK (development kit), not just the JRE (runtime environment).

1a. Check whether you have Java, and what flavor

To check whether you have Java, run the following in a command window:

On Mac OS X, run:

/usr/libexec/java_home

You should see something like this, assuming your JDK is version 7 (also known as 1.7):

/Library/Java/JavaVirtualMachines/jdk1.7.0_67.jdk/Contents/Home

On Windows, run:

echo %JAVA_HOME%

You should see a directory path that includes the letters ‘JDK’, something like this:

C:\Program Files\Java\JDK7

If you don’t have the JDK, download and install it. If the above commands don’t work, you don’t have Java or the setup is incorrect. Follow the installation and setup instructions below.

1b. Install and set up the JDK

Follow Oracle’s JDK installation instructions for:

If you’re on Windows:

    • Where the instructions say Updating the PATH Environment Variable (Optional), treat it as mandatory, not optional. This will make your life much easier.

    • Also set your JAVA_HOME environment variable. See Setting JAVA_HOME on Windows, from Kaan Mutlu’s Blog.

Here’s another useful guide: A JDK installation guide on dummies.com.

2. A text editor of your choice

If you don’t have a preference, try Komodo Edit. Komodo Edit is a free, open source edition of the full Komodo IDE.

3. Eclipse

It will be handy to have Eclipse, a free and open source IDE (integrated development environment). The Eclipse IDE for Java Developers is a good one to have.

4. Chrome

The Chrome browser has some useful development tools. A different browser is fine too, if you’re comfortable with its web development tools.