Category Archives: technical writing

A technical writer’s mission statement

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:

 

Inspired by technical communication

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:

Inspiring mushroom

Webinar on API technical writing – June 2015

On Friday 19th June I’m presenting an hour-long webinar, an introduction to API technical writing. The webinar is hosted by the Technical Communicators Association of New Zealand (TCANZ, also known as TechCommNZ).

The session is a 60-minute introduction to APIs (application programming interfaces) from a technical writer’s point of view. It’s designed for an audience of technical writers who’re interested in learning about APIs and API documentation, and who’re looking for pointers about how to get started as an API technical writer.

Quick signup details: Anyone is welcome to join the webinar. You don’t need to be a member of TCANZ. (There are different fees for members and non-members.) To join the webinar, first sign up for a username on the TCANZ website (click Create Account on the TCANZ website), then register for the webinar on the webinar page.

More about APIs and the webinar

APIs are an exciting area of software development. In the online world, APIs provide the communication channel between one application and another. How does WordPress display your Twitter stream on your blog’s sidebar? By using the Twitter API. How does Confluence wiki display a set of Flickr photographs on a wiki page? Via the Flickr API.

Join us to see a couple of APIs in action, to find out what API documentation consists of, and to learn more about the role itself.

Webinar title: Introduction to API Technical Writing
Date: Friday 19 June 2015 (New Zealand/Sydney time zone)
Time: 11am in New Zealand, 9am in Sydney (see the World Meeting Planner for more time zones)
Cost and signup: See the TCANZ webinar page

Session summary:

  • 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.
  • Types of APIs, including REST APIs, other web services, library-based APIs like JavaScript, and more.
  • A couple of live demos of APIs that you can play with at home: a JavaScript API and a REST API.
  • 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.

API tech writing workshop in Sydney – you’re invited

On Monday 27th July we’re running a full-day workshop in Sydney, on API technical writing. It’s free, and you’re invited. There’s free food too!

The workshop is happening in collaboration with the Australian Society for Technical Communication (ASTC), also known as the TWIA. Anyone interested in learning about this role is welcome to attend – you don’t need to be a member of the ASTC/TWIA.

Quick signup link: Register to attend the workshop on Eventbrite.

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!

Workshop details

Date: Monday 27th July 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 workshop is held in the Google offices in Sydney: 1 Darling Island Road, Pyrmont NSW 2009 (Google Maps: https://goo.gl/maps/zypa1). When you arrive, report to the reception desk on the ground floor and say that you’re attending the API Technical Writing workshop at Google.

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

More details and how to sign up

To register for the workshop, visit the Eventbrite registration page.

I’m looking forward to meeting a number of new Sydney technical writers and seeing old friends too. Hope to see you there!

workshop-slide

(A slide from the workshop)

Now you can add items to Tech Comm on a Map yourself

A smart colleague showed me how to tweak the data source for Tech Comm on a Map so that I can allow data entry via a form, and moderate each entry before it appears on the map. This means technical writers around the world can add items to the map directly, instead of  asking me to do it via a comment on this blog. Too cool!

Would you like to add a conference, society, group, business, or educational course to the map, or some other titbit that technical writers will find interesting?

Use this online form to add an item to the map.

Any items you add will be saved for moderation, and will appear on the map once they’ve passed review.

Background info

Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. Read more about Tech Comm on a Map or see it in action.

Tech Comm on a Map

Follow

Get every new post delivered to your Inbox.

Join 1,588 other followers

%d bloggers like this: