API Workshop – TC Camp 2015

Notes Posted!

Check out the slides, video, Tom’s blog post, and notes from the scribe!

API documentation in changing environments with expanding/new technologies.

Learn how to document Java and C++ APIs using Javadoc and Doxygen. Also learn the basics of REST APIs, see sample REST API doc sites, and learn how to create interactive endpoint documentation. Need we say more! This is a must have skill set so sign up to reserve your space in the extremely valuable workshop.

To best prepare for the workshop so as to participate in some of the activities Tom has planned, it will be helpful to have the following installed:

  1. Eclipse IDE for Java: https://eclipse.org/downloads/packages/eclipse-ide-java-developers/keplersr1
  2. Java Development Kit (JDK): http://www.oracle.com/technetwork/java/javase/downloads/index.html
  3. Git: http://git-scm.com/book/en/v2/Getting-Started-Installing-Git
  4. Chrome: https://www.google.com/chrome/browser/desktop/
  5. JSON Formatter extension for Chrome: https://chrome.google.com/webstore/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa?hl=en
  6. A text editor, such as Notepad++ for Windows: http://notepad-plus-plus.org/ or Sublime Text for Mac: http://www.sublimetext.com/

If you don’t have them installed, that’s okay. But the activities won’t be as meaningful to you.

Also, given some recent surveys about API doc on his blog, he realized that by far the most interest with APIs is with REST APIs. As a result, he is planning to give a lot more emphasis to REST APIs, but also cover Java. He won’t have as much time to get into C++ as he had hoped, so if you had your heart set on deep diving into C++, let him know.

If you have any questions or any special topic requests for the workshop, feel free to drop him a note as well. He would like to have a general sense of what you’re hoping to get out of the workshop in terms of specific API doc information.

Presenter: Tom Johnson, I’d Rather Be Writing

Time: 8:30 AM to 10:30 AM

View the Slides

About our presenter

Tom JohnsonTom Johnson is a senior tech writer at the 41st Parameter in the San Jose area. An avid bicyclist and dutch-oven camper, he likes to go on early morning rides before his 4 daughters and wife awake. One time, on an early morning ride in Yosemite, he saw a bear at the edge of camp. Rather than riding away from the bear, he rode slowly over to the bear, introduced himself, and ate trail mix and drank orange juice with the bear while watching the morning sun rise. It was, he says, one of the most interesting moments of my life, for it turns out the bear was a curiously-minded creature who dreamed of documenting human customs and outdoor traditions — usually before eating them. But we connected on a intellectual level and decided to treat each other with mutual respect.

Video of the Session

Watch it on YouTube: https://www.youtube.com/watch?v=0yfNd7tzH2Q

Notes from the Scribe

Tom’s blog post

At the event:

Scribe: Laurie d’Armien

Top Takeaways:

  • IS API documentation for me?
  • REST APIs are a better fit for the web
  • Get on the API documentation group on LinkedIn
  • Doc for on-line, one page use. The API ref is the first place programmers look
  • Auto doc solutions are 1) swatter 2)RAML
  • Not used: PDF, multi-page web, DITA, ePUB, comments on pages, wikis, video