Workshop: API Technical Writing
Date: |
Friday, January 23rd, 2015 |
Time: |
9am to 4pm |
Location: |
Room “Araujo Tech Talk”, level 1, 1295 Charleston Rd, Mountain View, CA 94043 (Google Maps: https://goo.gl/maps/yW1hu). See the Parking Details section below. |
Cost: |
None. The course is given free of charge, sponsored by Google and the STC Silicon Valley Chapter. |
Instructor: |
Sarah Maddox |
Registration: |
|
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 course 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 and a JavaScript API.
Lecture: JavaScript essentials.
- Hands-on: Use JavaScript to exercise the sample JavaScript API in a more indepth manner.
Lecture: The components of API documentation.
- Hands-on: Generate reference documentation using Javadoc.
Lecture: Beyond Javadoc other doc generation tools.
Catering
We will provide lunch, and morning and afternoon refreshments. Please inform us of any dietary restrictions you may have.
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 current version of the Java SE JDK – the latest version of Java SE 7 is fine. (At time of writing, this is 7u71/72.) 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_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. Useful guides:
A JDK installation guide on dummies.com.
The Atlassian Confluence guide to installing Java is applicable for general JDK installation too.
Oracle’s JDK installation instructions: Windows and Mac.
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.
Prerequisites
This course 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 course:
For overviews of API technical writing: The September 2014 edition of the STC’s intercom magazine.
For a quick introduction to JavaScript: The JavaScript Tutorial from w3schools.com.
Parking Details
Here are some details about parking near 1295 Charleston Rd, Mountain View (Google Maps: https://goo.gl/maps/yW1hu):
- There are several parking lots next to building 1295. You can park in any unmarked spot. Avoid spots that are marked for expectant mothers or other special requirements.
- If parking immediately near building 1295 is full, you can park in the lots near building SB50 (1350 Shorebird Way). See the image below.
- You can also make use of the valet parking between 1245 & 1225 Charleston Rd.
Questions?
If you have any questions about the workshop, contact Sarah Maddox (the instructor) at sarahmaddox@google.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 the Android Location APIs. 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
Workshop Registration
Note that the workshop capacity is 110 people. Registration is first-come, first-served. Once we reach capacity, registration will be closed and a wait list will be enabled. If you register and wish to cancel later, log into EventBrite and cancel your order.
For questions, contact progmgr@stc-siliconvalley.org.