Category Archives: STC
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!
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.
Yesterday I was privileged and delighted to speak at a meeting of the STC Silicon Valley Chapter in Santa Clara. Thanks so much to Tom Johnson and David Hovey for organising the meeting, and thank you too to all the attendees. It was a lovely experience, with a warm, enthusiastic and inspiring audience. This post includes some links for people who’d like to continue playing with the APIs we saw last night and delving deeper into the world of API documentation.
The presentation is on SlideShare: API Technical Writing: What, Why and How. (Note that last night’s presentation didn’t include slide 51.) The slides include a number of links to further information.
The presentation is a technical writer’s introduction to APIs (Application Programming Interfaces) and to the world of API documentation. I hope it’s useful to writers who’ve had very little exposure to APIs, as well as to those who’ve played with APIs a bit and want to learn about the life of an API technical writer.
Here’s a summary of the presentation:
- Introduction to the role of API technical writer.
- Overview of the types of developer products we may be asked to document, including APIs (application programming interfaces), SDKs (software development kits), and other developer frameworks.
- What an API is and who uses them.
- A day in the life of an API technical writer—what we do, in detail.
- Examples of good and popular API documentation.
- The components of API documentation.
- Useful tools.
- How to become an API tech writer—tips on getting started.
Demo of the Flickr API
During the session, I did a live demo of the Flickr API. If you’d like to play with this API yourself, take a look at the Flickr Developer Guide (and later the Flickr API reference documentation). You’ll need a Flickr API key, which is quick and easy to get. Slide 23 in my presentation shows the URL for a simple request to the Flickr API.
There are more links to follow in the presentation itself: API Technical Writing: What, Why and How. I hope you enjoy playing with some APIs and learning about the life of an API technical writer!
This week I attended STC Summit 2014, the annual conference of the Society for Technical Communication. This year the conference took place in Phoenix, Arizona. The temperature was 40 degrees Centigrade (over 100 F) when I arrived. Phew!
Hot temps outside, hot topics inside. The conference started with two days of workshops, followed by three days of lectures and learning sessions. There were 7 time slots each day, with as many as 20 tracks running simultaneously. So, plenty of sessions to attend, plenty of topics to take in, and plenty of people to meet. I feel as if I haven’t stopped moving since I touched down in Phoenix on Sunday morning.
I blogged about most of the sessions I attended. There were two more where it was just not practical to take notes. One was a series of 5-minute lightning talks, very entertaining, but too fast to do justice with notes. The other session took place just before my own, and I was very busy trying to still my nerves and get in the zone, so I didn’t even try to take notes.
Here are my write-ups, in reverse chronological order:
- 7 Archetypes of Video Storytelling
- Patient Education and Health Literacy
- The Making of “The Language of Content Strategy”
- Information Architecture Bottom Up
- Google Glass and Augmented Reality
- API technical writing (This was my presentation)
- Key Trends in Mobile Publishing
- How technical writers can build personal influence
- Content strategy versus wicked ambiguity
For a full list of sessions, visit the conference site on Lanyrd.
Any more write-ups?
The STC’s Notebook has some information about the conference, as well as about the STC in general.
If you spot any more posts about the conference, please would you add a comment to this post? I’d love to read them.
Thanks and kudos
A huge vote of thanks to the STC Summit committee and all the people who took part in making this such a great event. From my viewpoint as speaker and attendee, the organisation was flawless. The Phoenix Chapter of the STC put on a big welcome, and put in a huge amount of work behind the scenes to make everything flow smoothly. It was a lovely experience from start to finish.
Thanks also to all the speakers, who put so much work into their presentations. And to the attendees, without whom the conference would be so much the poorer. It was a great pleasure to meet old acquaintances and to make so many new ones too.
I took this photo in the Desert Botanical Gardens in Phoenix:
This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.
This session promises to offer The Content Wrangler at his best: Scott Abel on “The Power of Emotion: The Seven Archetypes of Video Storytelling”.
We’re wired for stories. Human beings are designed to consume stories. It’s how we understand things.
Stories are an art form. They’re often performed, and it’s the emotion in the story that makes us remember them.
Seven recurring themes
Scott showed us examples videos that harness the 7 recurring themes or story archetypes:
- Overcoming the monster. David and Goliath, good versus evil, nature versus machine.
- The rebirth, revival, renaissance.
- The question. A mission to change things for the better.
- The journey, or the return. Moving from one idea to another, or growth.
- Rags to riches. Overcoming adversity or poverty.
- Tragedy. An unhappy ending, or a twist that you don’t expect, almost always involving the main character.
- Comedy. Humour, sometimes with a little satire.
We also saw a cute hybrid: a musical comedy
Scott says we need to think about how we’re going to tell stories in our new world of interconnectedness. Send out our message on all channels – the omni-channel approach.
See the retelling of Cinderella in the video below: “Transmedia Storytelling” – liquid content that’s adaptable for distributing to different media. A different way of telling stories altogether.
Cinderella 2.0: Transmedia Storytelling
Don’t be afraid to use emotion to engage your audience!
This was a cute, amusing and engaging session. :)