(Untitled)

For questions, please contact the events manager: events@events.stcwdc.org

Loading Events

« All Events

  • This event has passed.

API Documentation Workshop with Sarah Maddox

20 Mar 2015 @ 9:00 am - 4:00 pm UTC-4

Free

Workshop: API Technical Writing

Sponsors: Google, Group Wellesley, Inc., STC WBDC Chapter, InfoDevDC Meetup Group.

Date: Friday, March 20th, 2015
Time: 9 am to 4 pm
Instructor: Sarah Maddox
Cost: None. The workshop is given free of charge.
Location: Room: “The White Space”, 9th Floor, 25 Massachusetts Ave NW, Washington, DC 20001 (Google Maps: http://goo.gl/A4FqJ8). A parking garage is connected to the building. To see parking rates and hours, search for the address on the parking locator.

The venue is within a 10-minute walk from Washington DC Union Station and the Red Line Union Station stop on the Washington Metrorail.

Workshop Description

This is a practical course on API technical writing, consisting of lectures interspersed with hands-on sessions where participants will apply what they have learned. The focus will be 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 will include 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.

Catering
 
Google will provide lunch, and morning and afternoon refreshments, free of charge. Please inform us of any dietary restrictions you may have.
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, and an acquaintance with CSS. 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.

An introduction to JavaScript: The JavaScript Tutorial from w3schools.com.

What to bring and what to install

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 current version of the Java SE JDK. Make sure you have the JDK (development kit), not just the JRE (runtime environment).

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

On Mac OS X, run: /usr/libexec/java_homeYou 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 FilesJavaJDK7

If you don’t have the JDK, download and install it. If the above commands don’t work, your setup is incorrect – follow the installation and setup instructions again.

To install and set up the JDK:

Follow Oracle’s JDK installation instructions:

For Windows.

For Mac.

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 are some other useful guides:

A JDK installation guide on dummies.com.

The Atlassian Confluence guide to installing Java – applicable for general JDK installation too.

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 (optional)

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 and add-ons. In particular, we’ll be using a Chrome add-on for sending requests to a REST API. A different browser is fine too, if you’re more comfortable with its web development tools.

Questions?

For questions about the workshop content, contact Sarah Maddox (the instructor) at
sarahmaddox@google.com.

For questions about the registration process, contact Alan Houser, arh@groupwellesley.com.
About the instructor

Sarah Maddox is a technical writer in Google’s Developer Platforms team, writing the documentation for the Google Maps APIs and Google Places API. She’s also worked at Atlassian and many other organisations around the world. With fifteen years’ experience as a technical writer and ten as a software developer, Sarah specialises 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
 
 

Print Friendly, PDF & Email

Viqui Dill is the STC Washington, DC-Baltimore Chapter's social media manager. Viqui describes herself as "Technical writer, wife and mom, bass player, worship leader, I'm happiest when folks sing along with me."

Venue

Google Washington DC
25 Massachusetts Avenue Northwest, #900
Washington, DC 20001 US

Viqui Dill is the STC Washington, DC-Baltimore Chapter's social media manager. Viqui describes herself as "Technical writer, wife and mom, bass player, worship leader, I'm happiest when folks sing along with me."

Leave a Reply

Your email address will not be published. Required fields are marked *