01. Sarah Maddox: API Technical Writing (September 21, 2015)
Sarah Maddox presents:
API Technical Writing
sponsored by Google
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:
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
For questions about the workshop content, contact Sarah Maddox on firstname.lastname@example.org.
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):
A text editor of your choice
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:
You cannot walk in.
To register for this event, go to the Register section below and sign up in advance of the registration deadline.
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.
- 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.
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:
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.
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.
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.
The Chrome browser has some useful development tools. A different browser is fine too, if you’re comfortable with its web development tools.