Category Archives: STC

Talking about APIs and Maps at STC Summit 2017

I’m excited to be speaking soon at STC Summit 2017, the annual conference of the Society for Technical Communication. The event happens in Washington, DC, on 7-10 May. My presentation is about APIs, maps, developers, and a tech writer’s foray into the world of app development.

The conference theme is “gaining the edge”. So I decided to talk about my experiences developing an app, and why I tried my hand at app development. The app, Tech Comm on a Map, is an interactive web-based map that shows events of interest to technical communicators.

In this presentation, 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.

Follow me on a tech writer’s odyssey into app development.
Tread in dangerous territory.
We may even see a dragon or two.
Emerge a little triumphant, and certainly well travelled.

Q: Why does the journey on this map start in Sydney and end up on the east coast of the US?
A: Because that’s the trip I’ll make to give this presentation at STC Summit. 🙂

At this session, you’ll learn the technical details:

  • The nuts and bolts of a web-based application like Tech Comm on a Map: where it’s hosted, where the data is stored, the JavaScript code and the APIs that create the map and the app’s functionality.
  • 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. Tech Comm on a Map is available as a native Android app as well as a webapp.
  • The information sources that I used when developing the app.

You’ll also see how such a project can help develop your soft skills:

  • My engineering colleagues helped me 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.

Here’s the session on the STC Summit schedule: A tech writer, a map, and an app.

You can also read more about the app, Tech Comm on a Map.

What do you want to know about Tech Comm on a Map?

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.

Tech Comm On A Map

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.

Blurb

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.

Tech Comm on a Map for AndroidOne 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.

Outline

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:

  • The nuts and bolts of a web-based application like Tech Comm on a Map: where it’s hosted, where the data is stored, the JavaScript code and the APIs that create the map and the app’s functionality.
  • 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.

Webinar on API technical writing with STC India

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.

Registration details: Sign up for the webinar, and read more about it on the STC India site.

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.

Topic overview:

  • 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. 🙂

Inviting Seattle tech comm students to speed networking and workshop

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:

Here’s the poster the STC shared with me, for the speed networking event:

Tech comm networking poster

 

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!

Seattle workshop on API Technical Writing

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.

Quick links: Register to attend, and learn more on the STC Puget Sound site.

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.

Workshop details

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:

  • Lecture: Introduction to APIs, including a demo of some REST and JavaScript APIs.
  • Hands-on: Play with a REST API.
  • Lecture: JavaScript essentials.
  • Hands-on: Play with a JavaScript 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:

Working with an Engineering Team

%d bloggers like this: