Category Archives: STC
I’m putting together a presentation about Tech Comm on a Map, the app that shows technical communication events and groups around the world. What would you like to know about the web app and the Android app for Tech Comm on a Map?
It’s a little scary for a tech writer to create and publish an app. Actually, it’s a little scary for anyone. Are you curious about any particular aspects of why I did it, what the results are, or anything else? If I can, I’ll weave the answers into the presentation.
I’ll be speaking about Tech Comm on a Map at STC Summit 2017 in May, and possibly at other events after that. At the moment, I’m writing the presentation based on my early proposal and outline. I’m having fun! But before I get too invested in what I think is fun, I’d love to hear what other people think too.
The theme for STC Summit 2017 is “Gain the Edge to Get Results“.
Here’s the blurb and outline from the proposal I sent to the STC Summit committee.
As an API technical writer, it’s hard to put yourself in the shoes of your readers. They’re application developers. They’d rather read code than prose.
One way of grokking this audience is to develop an app yourself.
This presentation tells the story of a tech writer, a map, and an app. The app is Tech Comm on a Map, an interactive web-based map that shows events of interest to technical communicators. You’ll hear why Sarah decided to create an app and how she went about it. You’ll see some code and understand the nuts and bolts of the app: where the data is stored, how it gets there, how it ends up on a map for everyone to see.
Tech Comm on a Map is an app for technical communicators, and technical communicators contribute to the data. Sarah will describe the process of crowd-sourcing the data and open-sourcing the app: what went well, what went slowly, what’s still going.
Writing an app has helped Sarah understand her audience (software engineers), her subject matter (APIs), and her profession (technical communication). Come and see how.
It’s hard to create an app. It’s even harder to get the app published and make it available to other people. That’s true whether you’re a developer or a technical writer. You need to put yourself on the edge and take the jump. You need courage, strength of conviction, and knowledge. Above all, you need documentation and examples. They give you the edge.
By taking the jump into app development, Sarah has gained first-hand knowledge of what developers go through. She applies this knowledge to the documentation she writes. It’s also a lot of fun!
At this session, you’ll learn the technical details:
- How the app’s data is crowd-sourced.
- What open sourcing your code means, and why you may want to do it.
- The difference between a web-based application and a mobile app, from a developer’s as well as a user’s point of view. Tech Comm on a Map is available as a native Android app as well as a webapp.
- The information sources that Sarah used when developing the app.
You’ll also see how such a project can help develop your soft skills:
- Sarah’s engineering colleagues helped her kick off the development of the app, and made ongoing suggestions for refinement. The resulting interactions increased mutual understanding and respect.
- Fellow technical writers all over the world help compile the data. A project like this is a good way of connecting with your peers.
- Developing an app can help you better understand your subject and your audience of software engineers and other specialists.
- Such a project gives you confidence in your own abilities, even if you’re just skimming the surface of code complexity.
See Tech Comm on a Map in action at https://sarahmaddox.github.io/techcomm-map.
What are you curious about?
Does the above description raise any specific questions in your mind? Is there something you’re very keen to find out? Let me know, and I’ll include it in the presentation if I can.
Are you interested in learning about APIs and API technical writing? Join us for a webinar, hosted by STC India. I’ll demo a couple of APIs and discuss the role of a technical writer in this area of the software industry. We’ll look at examples of API documentation, and discuss what type of documents an app developer expects when using an API.
The title of the webinar is “Introduction to API Technical Writing”. It’s intended for technical writers who know little about APIs (application programming interfaces) and want to explore the field of API technical writing. My hope is that, after attending this webinar, you’ll have the knowledge and tools you need to head off on your own explorations.
APIs (application programming interfaces) make it possible for applications to share information with each other. You could say that APIs are the communication channel of the online world. Developers need help hooking their application up to someone else’s APIs. We, as technical writers, give them that help.
Recording of the webinar [Update on 10 April 2016]: The recording of the webinar is now available on YouTube: Introduction to API Technical Writing.
Date and time: Friday 18 March 2016, at 1pm Indian time – that’s 6.30pm in Sydney. The session lasts one hour.
Who can join? Anyone. It’s free of charge, and you don’t need to be a member of the STC.
- An introduction to APIs.
- An overview of the role of API technical writer.
- Our audience – the developers who need our documentation to use APIs in their applications.
- The types of API we might be asked to document.
- Demos of 2 APIs that you can play with yourself.
- What API documentation consists of.
- Examples of good and popular API documentation.
- Working with engineers.
- Tips on getting started as an API technical writer.
Hope to “see” you at the webinar. 🙂
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!
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. 🙂 Join me and other Google tech writers in a day of API doc lectures and hands-on sessions.
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.
Meet Google tech writers
There’ll be some Google tech writers at the workshop, assisting with any difficulties during the hands-on sessions. I’m hoping a couple of them will present some of the lectures too.
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:
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!