Preparing for the Pre-Camp Full-Day API Workshop – TC Camp 2016

Location:
Google Tech Corners campus
Room TC2-1-Blade Runner Tech Talk
807 11th Avenue, Sunnyvale, CA 94089

Date: Friday, January 22, 2016

Time: 9am to 4pm (breakfast and setup are at 9am, for a start at 9:30 sharp)

Instructor: Andy Fuchs, Joe Medley, Sarah Maddox

Cost: None. The workshop is given free of charge. Pre-registration is required; this workshop is full and wait-listed.

Workshop Description

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

Catering

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

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:

What to bring

Bring your own laptop with a WiFi connection and power cable. Please install the following software before the workshop.

Install the 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).

Check whether you have Java, and what flavour:

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.

Install and set up the JDK:

  • Follow Oracle’s JDK installation instructions:
  • 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.

Install 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.)

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

Install Chrome

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

Get a Flickr username

You can do this during the workshop, but it will save you time if you do it beforehand. You’ll use your Flickr account during the workshop, to experiment with the Flickr API.

To get a Flickr account:

  1. Go to Flickr.com in your browser.
  2. Click the Sign In link at top right.
  3. Follow the prompts to create a new Yahoo account if you don’t yet have one, or log into your existing Yahoo account. (Yahoo owns Flickr.)

3 thoughts on “Preparing for the Pre-Camp Full-Day API Workshop – TC Camp 2016”

Comments are closed.