Author Archives: Sarah Maddox
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?
I’m excited and delighted to announce that I’ll be presenting a one-day workshop on API technical writing, in conjunction with the Silicon Valley Chapter of the STC (Society for Technical Communication).
The workshop will be 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 will be on APIs themselves as well as on documentation, since technical writers need to be able to understand and use a product before we can document it.
Date: Friday, January 23rd, 2015
Time: 9 am to 4 pm
Location: 1295 Charleston Rd, Mountain View, CA 94043 (Google Maps: https://goo.gl/maps/yW1hu). The building is on the Google campus. The workshop takes place in the “Araujo Tech Talk” room on level 1.
Cost: None. The course is given free of charge, sponsored by Google and the STC Silicon Valley Chapter.
- STC membership is not required.
- The course is currently fully subscribed. But it’s worth adding your name to the waiting list, in case a place becomes available closer to the date. We’ll check the number of tickets and the waiting list early in January.
- If you’ve registered but later find you’re unable to attend, you can cancel your order in EventBrite. This will open up a place for people who are on the waiting list.
The course will include the following sessions:
- Lecture: The components of API documentation.
- Hands-on: Generate reference documentation using Javadoc.
- Lecture: Beyond Javadoc – other doc generation tools.
Details and signup
For details of food, what to bring, prerequisites, and how to sign up via EventBrite, please head on over to the STC Silicon Valley workshop page.
Here’s some information 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):
- You can also make use of the valet parking between 1245 & 1225 Charleston Rd.
Questions and comments
Please let me know if you have any questions or comments.
Tech Comm on a Map now displays all the 2015 technical communication conferences that I’ve found so far. Take a look, and let me know if there are any more tech comm conferences, groups, businesses or societies to add.
Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. It’s a great way of seeing what we tech writers are up to, around the world. To find out more about the project, or to add something to the map, check out the project information page.
A new theme is emerging in the UX (user experience) world: Empathy. Putting humanity into technology. Product designers want to ensure they have empathy with the users of their product. We in the tech world want to design for what people need and want, rather than for what’s new and shiny. I think technical writers can contribute to this discussion!
Last month I attended Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. A strong theme emerged at the conference: Empathy, what it means to be human in a digital world, creating an internet for humans… What’s more, this was a spontaneous emergence, not suggested by the conference organisers. It just happened.
My deduction was that this must be a “thing” in the world of web design and development at the moment, whether conscious or unconscious, whether generally known or just beginning to seep into our collective consciousness.
I’m wondering: how many other people have encountered this theme?
Since then, I’ve read a post by Georgina Laidlaw, entitled “Why Don’t You Have a Writer in Your UX Team?” (linked at the end of this post). Georgina was recently at the UX Australia Redux conference in Melbourne, where she noticed a “dearth of writers”. She follows that observation with an excellent and exciting description of the contributions a technical writer can make to a UX team: “five things a great writer knows better than anyone else in the room”. I’ll resist simply listing the five bullet points, because such a bald list wouldn’t do justice to Georgina’s post.
Georgina’s third point struck a chord: “Writers understand empathy“. She says,
Writers deal with emotion all the time. Even the writer of the blender manual is working to avoid frustrating or patronizing you, and to make things seem achievable so that you feel an affinity for the product you’ve bought.
Every professionally written item aims to communicate, and to do that, the writer needs to deal with emotion. They’re skilled at empathising with the target audience — the users of their words — whether that’s on a single-word basis, or a thousand-word basis.
I’d add these points: As technical writers, we focus on analysing our audience, thinking about how our customers work, what they want, and what they need. We get to see early version of the product we’re documenting, whether that be an app, an API, a piece of hardware, or another type of product. We exercise the product as a user would, in order to document its usage. Many of us interact with customers, via feedback on the docs, in forums, or in other ways. We see a different set of customers from those the product managers and marketing/sales teams focus on: we see and think about the “end users” (for want of a better term).
We can chat to the engineers, designers and product managers we work with, to share our insights. We can make ourselves known early in the design phase of a product, again to share our insights and also to expand our own knowledge of the product aims.
So, yes to Georgina and other UX specialists: let’s talk. :)
Here’s a link to Georgina Laidlaw’s post on SitePoint: Why Don’t You Have a Writer in Your UX Team? It’s well worth a read.
A pic from me, for fun:
This week I attended Web Directions South 2014, a conference for people who “design, imagine, create or build digital products, web sites and applications”. I’ve blogged about most of the sessions I attended. This post is a summary of my impressions, with links to the more detailed posts.
This was a technical conference for technical folk. Yet the presentations that went down best were those that mixed the human side in with the tech. Those that gave techniques for handling situations and people as well as code. Those that included humour and people in the slides. Code is for people by people.
A theme stood out in the keynote presentations and many of the other sessions: putting humanity into technology. There’s a concern that technical design focuses on what’s cool and new, when it should rather focus on what people need and how users want to interact with their tech.
The quality of the sessions overall was excellent. In particular, Sarah Mei’s presentation on day 1 gave me a lot to think about. Her idea is innovative and unusual: to analyse the way we make technical decisions, so that we can then apply the same process to the harder tech decisions. Jeremiah Lee’s talk on day 2, about what makes an excellent API, had some excellent nuggets of information that were particularly relevant to me as an API technical writer. I especially liked the bit about passive usability testing via analysis of existing data.
My own presentation was on day 1: Bit Rot in the Docs. It was a bit freaky – the sessions took place in a theatre, so I was literally on stage, with bright lights shining down on me and the audience in tiers of seats extending into the blackness.
Looking for more pics? Try Xavier Ho’s photos. There’s even one of me giving my presentation. (I’m in the fourth row of photos, third from the left.)
Here are my detailed notes:
- Web Directions 2014 – day 1
- Web Directions 2014 – day 2
- Web Directions 2014 – Being human in a digital world
- Bit rot in the documentation
- Web Directions 2014 – Interconnected
A huge thanks to Maxine Sherrin and John Allsopp for the hard work and dedication they put into organising Web Directions. Thanks also to all the presenters and attendees. It was a great experience! Oh, and one final observation: The chocolate brownies were to die for.