Will you be in Seattle on Friday, October 23rd? Join me and the Puget Sound Chapter of the STC for a full-day workshop on API technical writing. It’s free, and there’s free food too. :)
Anyone interested in learning about API technical writing is welcome to attend – you don’t need to be a member of the STC.
What is API technical writing?
API stands for Application Programming Interface. Developers use APIs to make apps that communicate with other apps and 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 tech writer, it’s an exciting, challenging and rewarding field. I love it!
This workshop gives you hands-on experience with APIs and API documentation, insight into the demands of the role, and plenty of information for your own follow-up study.
Date: Friday, October 23rd, 2015
Time: 9am to 4pm – breakfast and setup are at 9am, for a start at 9:30 sharp
Instructor: Sarah Maddox – that’s me ;)
Cost: None. The workshop is given free of charge.
Location: Google Offices, 601 N 34th Street, Seattle, WA 98103. (Link on Google Maps.)
This is a practical course on API technical writing, consisting of lectures interspersed with hands-on sessions where you’ll apply what you’ve learned. The focus is on APIs themselves as well as on documentation, since we need to be able to understand and use a product before we 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
Preparation for the workshop
Please take a look at the prerequisites and setup to see what you need to install on your laptop before the workshop. Doing the recommended installations will save you a lot of time at the workshop so that you can avoid missing crucial bits when you’re there.
Hope to see you there!
Here’s that signup link on Eventbrite. I hope to see you there!
Slide from lecture – working with an engineering team:
What are the most inspiring, exciting areas of technical communication? I think this is a cool topic to explore. I’m hoping we have many different ideas and perspectives. Even better, I’m hoping that each of us thinks the area we’re personally working in is the most inspiring of all!
Why am I asking this question right now? Well, I do think it’s a very cool topic that will give us insight into the depth and breadth of our field. Also, I’m thinking of incorporating this topic into an upcoming presentation. If you’d like to add some thoughts via comments on this post, I’ll credit you with anything that I mention in the presentation.
To get the ball rolling, I’ll say that API technical writing is the best. :) It’s no secret that I love my role and talk about it non stop. Being so deeply immersed in APIs, I have the opportunity to play with them myself, build stuff with them, and show other people how they work. It’s a demanding, constantly challenging role – but that’s the way I like it.
It comes down to this:
APIs are the communication channel of the online world.
Developers need help hooking their apps up to someone else’s API.
Technical writers who can give that help are in a very good position.
Other inspiring or even revolutionary tech comm?
There are other areas of tech comm that seem equally appealing, at least from afar. How about documenting the software used by 3D animation specialists, or tools used by artists, or the games industry, or smart hardware, or the medical industry?
Perhaps there are tech writers working in areas that are revolutionary as well as inspiring. Here’s a challenge: top my description of API tech writing if you can. :)
An inspiring mushroom
I came across this Veiled Lady Mushroom while walking in the bush near Sydney, Australia:
What’s the difference between delete and remove? When should you use the word “delete” on a user interface or in a document, and when “remove”? Here’s an explanation that makes sense to me.
Use “delete” when you’re getting rid of the thing entirely – when it’s disappearing from the data store. Use “remove” when you’re subtracting it from a group or a list, but it remains available in the data store.
An example is the model of users and groups. Let’s say the user
arthurdent belongs to two groups:
earthlings. When Arthur no longer lives on planet Earth, you would remove
arthurdent from the
earthlings group. But if Arthur has departed the universe without leaving so much as a towel behind, you would delete the username
Here’s another example. Let’s say you have a number of credit card charges, which you’re adding to two expense reports. By mistake, you’ve added one of the charges to Expense Report 1 as well as Expense Report 2. So you need to remove that charge from the report. In addition, there’s an erroneous credit card charge of zero dollars, which you can delete without adding it to a report.
Works for me. :) What do you think?
On Wednesday February 11th, US EST (that’s Thursday here in Australia), I’m presenting a webinar about API technical writing. It’s the first in a series on API technical writing from the Society for Technical Communication. I’d love it if you could join me online.
The role of API technical writer is exciting, rewarding, and challenging. I’ve been working as a full-time API writer for 18 months now, and I love it!
APIs are a hot topic in our field, and technical writers with the skills to document them are in high demand. Many technical writers are keen to know more about the role, but it can be hard to find information. Sometimes there’s so much information that it’s difficult to know where to start. In presenting this webinar, my aim is to give you a good idea of the role of API technical writer, and some excellent starting points to explore the world of APIs.
Details of the webinar
Title: Introduction to API Technical Writing.
Date and time: Wednesday, 11 February 2015, at 2pm EST (GMT-5) – that’s 6am on Thursday here in Sydney!
Duration: One hour.
Fees and registration/signup: Please refer to the STC announcement: Part 1 in API Series: Introduction to API Technical Writing.
The session covers the following topics:
- What an API is and does.
- Introduction to the role of API technical writer and our audience.
- Overview of the types of developer products we may be asked to document – APIs and others.
- Examples of good API documentation.
- The components of API documentation, and the technical writer’s role in the creation of each component.
- A day in the life of an API technical writer.
- Tips on getting started in the role.
Here’s a link to the slides on SlideShare: API Technical Writing.
More in the STC’s webinar series on API technical writing
Following on from my introductory webinar, the next two sessions in the STC’s series have already been announced. In episode 2, Ed Marshall talks about documentating Java and C++ APIs. In episode 3, Joe Malin describes how to write effective code samples.
I hope to “see” you at the webinar!
The STC (Society for Technical Communication) is presenting a series of webinars (online seminars) on API technical writing, starting in February. I’m delighted to be presenting the first webinar in the series: Part 1: Introduction to API Technical Writing.
The role of API technical writer is exciting, rewarding, and challenging. In this webinar we’ll explore what an API is and does, see a couple of APIs in action (provided the demo gremlins stay away!), take a look at some examples of API documentation, and hear some tips on getting started in the role.
Details of the first webinar in the series
Date and time: Wednesday, 11 February 2015, at 2pm EST (GMT-5) – that’s 6am here in Sydney!
Duration: One hour.
Fees and registration details: Please refer to the STC announcement: Part 1 in API Series: Introduction to API Technical Writing.
Here’s an outline of the session:
- Introduction to the role of API technical writer
- Overview of the types of developer products we may be asked to document
- What an API is and who uses it
- A couple of live demos of APIs that you can play with at home
- Examples of good API documentation
- The components of API documentation, and the technical writer’s role in the creation of each component
- Tips on getting started as an API technical writer
Focus on APIs in the world of technical documentation
APIs are a hot topic in our field. Following on from my introductory webinar, the next two sessions in the STC’s series have already been announced. In episode 2, Ed Marshall talks about documentating Java and C++ APIs. In episode 3, Joe Malin describes how to write effective code samples.
Then there’s my upcoming API workshop in January (now fully subscribed) sponsored by the STC and Google. Tom Johnson runs an API workshop at TC Camp 2015. The September edition of Intercom focused on API technical writing. Tom Johnson has written some truly excellent blog posts on the subject over the last few months, the latest of which is a podcast with Joe Malin. Here’s a list of my own posts about APIs.
Are you into, or interested in, API tech writing?
Phew, a hot topic indeed. I’d love to know whether it’s something you’re interested in. Perhaps you’re dabbling in APIs, or already into them full time?