Category Archives: technical writing
The Puget Sound Chapter of the Society for Technical Communication (STC) is hosting a “speed networking” session at the University of Washington at 6pm on Tuesday, October 20th. I’m delighted to say that I’ll be there too.
In addition, you’re invited to an API Technical Writing Workshop that I’m running in conjunction with the STC on Friday, October 23rd. It’s open to students as well as people already in the tech writing field. See the details here.
So, that’s 2 tech comm events in one week – an opportunity not to be missed. :)
Quick registration links:
- Register for the speed networking event: http://bit.ly/HCDE-STC
- Register for the workshop: http://goo.gl/FYqCzf
Here’s the poster the STC shared with me, for the speed networking event:
Random remarks from me:
- I like the spelling of “alumnae”. At first I thought, “Gah, typo!” Then I realised it’s a thing.
- The purple colour is awesome. It matches my Ubuntu background!
I hope to meet many students and other Seattle tech comm folks at the networking event and at the workshop!
I’m very excited, because there’s an Android app on its way for Tech Comm on a Map. The Android app uses the same data source as the Tech Comm on a Map website – so you can see the same events on the map in both apps. In addition, you can add events to the map directly from within the Android app, and it does smart marker clustering too.
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 already out there on the Web. See it in action on the Tech Comm on a Map website, and read more on this page.
And now the Android app
The code for the Android app is already on GitHub. A group of us got together during a hackathon and created the initial version of the app. I’ve added to the app since then, and intend to continue improving it. Eventually I’d like to add it to the Google Play store. There’s a bit to do before that. :)
Friendly disclaimer: Although I work at Google, this app is not a Google product. It’s a personal project by me and the other contributors.
The Tech Comm on a Map app for Android is developed with Java and the Android SDK. It uses the following APIs:
- Google Maps Android API
- Google Places API for Android (Autocomplete and Place Picker)
- Google Play services Fused Location Provider (Get Current Location)
- Google Apps Script
- Realm.io (a mobile database)
- AndroidSlidingUpPanel (a draggable sliding-up panel)
- Android Saripaar (a validation library):
If you’re interested in developments, follow the Tech Comm on a Map app for Android on GitHub. You can build it from the source and load it onto your Android device to try it out. It works. :)
On Monday, September 21st, I’m hosting a full-day workshop in New York City, on API technical writing. It’s free, and you’re invited. There’s free food too!
The workshop is happening in collaboration with the New York Metro Chapter of the STC (Society for Technical Communication). Anyone interested in learning about this role is welcome to attend – you don’t need to be a member of the STC.
Quick signup link: Register to attend the workshop on the STC New York Metro website.
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: Monday, September 21st, 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: The Google offices in New York city: 76 Ninth Avenue, New York, NY 10011. (Link on Google Maps.) Enter through the tenant entrance at the corner of 16th St and 9th Ave, and report to the workshop registration table. (It will have Google-branded linen.)
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 event announcement 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 STC New York Metro site.
I’m looking forward to meeting a number of New York technical writers!
A slide from the workshop
I recently saw a thought-provoking article on cognitive overhead. It got me thinking about what we do as technical writers.
People learn by attaching a new idea to their existing context. The ability to help them do that is our killer skill. That’s the basis of the tutorials we write, for example: start from a known point and expand the reader’s knowledge.
Based on the above premise, here’s an idea for a technical writer’s mission statement:
Make complex goals achievable within our customer’s context
Originally I’d written “Make complex goals achievable within our reader’s context”. Then I thought the word “reader” may be too narrow, as we often create material in media other than the written word. Actually, that’s often the argument used for calling ourselves “technical communicators” rather than “technical writers”. But that’s another story. :) Anyway, I’m still leaning towards the earlier version of the mission statement:
Make complex goals achievable within our reader’s context
What do you think of these ideas for a mission statement?
After writing this article, I searched to see what other people have said on this topic. Here are some good posts:
- Why you need a tech comm mission statement, by Kai Weber.
- Sample mission statement, on TechWhirl.
- Our continuing mission…, by Karen Rempel.
- Mission Statement, by Kitsap Technical Writing
- The ComfyChair Mission Statement Generator – Click “Thank you Sir, may I have another” to generate a new mission statement. :)
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: