API Documentation for Beginners
A full-day training session
Take your technical writing to the next level by learning how to write application programming interface (API) documentation.
APIs provide the means to work with everything from libraries to web services and even hardware, and this applies for both commercial products and services as well as free open source software (FOSS). Adoption rates of a particular software product or package often hinge on the quality of the accompanying API documentation. This is a specific area in which competent technical writers can provide significant value to employers and colleagues.
In this full-day workshop, we’ll introduce you to the structures and concepts that you’ll need to understand in order to get started in this fascinating and lucrative domain. We’ll begin with an overview of how are APIs used, what makes good API doc, and how to organize an API doc project. We’ll then build on that by looking at RESTful services, object-oriented libraries, command line interfaces, and IoT devices to identify the specific needs of each of these API types. We’ll also touch on the common open source tools and formats (such as markdown, OpenAPI/Swagger) that you can use to manage and build your documentation.
To get the most from the workshop, bring a laptop or tablet with a text editor (such as Notepad++, SublimeText, Atom, etc.) and access to the web. We’ll do a number of exercises designed to reinforce the concepts presented in class. If you have even the most cursory knowledge of a programming language, that’d be great, but it isn’t required.
Links from the presentation
- Zipfile with the two HTML files (Docs as Code, and RESTful APIs)
J.A. Bujes has been writing software documentation for over thirty years, addressing topics like distributed computing, web services, operating systems, messaging middleware, source control systems, programming languages, development environments, and tools. She has also taught writing and technical writing at the college level.
Though her working days are winding down, she plans to write a textbook to share her experience and craft with aspiring technical writers. English majors have to eat too!
Paul Wallace has spent nearly a decade working concurrent roles as technical writer, doc tools developer, and localization engineer. He is a producer as well as avid consumer of API documentation, which he uses to write production code.
He currently works at Synopsys within its Software Integrity Group in San Francisco.
Date and time: Friday 26 April 2019, 8:30am (Registration), 9:00am-5:00pm (Class)
Location: Dr. Martin Luther King, Jr. Library – Room 255
Cost: $140. Lunch and parking provided.
About WIFI Access in the Library: https://www.sjpl.org/wireless
NOTE: Tickets for the API Training Full-Day Class
are sold separately from the unconference