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.
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:
- Hands-on: Play with a REST 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
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:
- Overviews of API technical writing: The September 2014 edition of the STC’s intercom magazine.
- A blog post positing a classification of APIs, from a tech writer’s point of view.
- What is the DOM? from W3C.
Bring your own laptop with a WiFi connection and power cable. Please install the following software before the workshop.
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:
You should see something like this, assuming your JDK is version 7 (also known as 1.7):
- On Windows, run:
You should see a directory path that includes the letters ‘JDK’, something like this:
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.
If you don’t have a preference, try Komodo Edit. (Komodo Edit is a free, open source edition of the full Komodo IDE.)
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.
Chrome browser has some useful development tools. A different browser is fine too, if you’re comfortable with its web development tools.
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:
- Go to Flickr.com in your browser.
- Click the Sign In link at top right.
- 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.)