Blog Archives

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

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

Designing a workshop and workbooks

Over the last couple of months I’ve been presenting workshops on API technical writing in various locations. The workshops last a full day, and consist of lectures alternating with hands-on sessions. During the hands-on sessions, which last an hour, the participants work through learning material and exercises in a workbook. I put quite a bit of thought into the design of the workshop and workbooks. A few people have commented that the resulting structure works well, so I’ve decided to blog about it in the hope other technical writers will find it useful.

I’ve run the workshop three times to date: once in Mountain View, in collaboration with the Silicon Valley Chapter of the STC (Society for Technical Communication); once more in Mountain View, for Google technical writers; and once in Washington, DC, in collaboration with the STC Washington, DC – Baltimore Chapter.

First I’ll describe the workshop as a whole, then I’ll focus on the workbooks designed for participants to work through during the hands-on sessions.

Content of the workshop

The workshop is an introduction to API technical writing, designed for an audience of technical writers who’re new to APIs.

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 technical writer, it’s an exciting, challenging and rewarding field.

The workshop includes the following parts, alternating between lectures and hands-on 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.

Design of the workbooks

When designing the content and structure of the workbooks, my aims were:

  • Consolidate the learning points from the previous lecture, by guiding people to perform the same tasks that they’ve just seen demonstrated.
  • Teach in-depth concepts and techniques that are better learned by active self-study than by watching someone else.
  • Provide material for further study after the workshop is over.
  • Cater for people with various skill levels in each subject area. Provide enough material for people who already know a bit about that particular subject, as well as for people just starting out.
  • Take the varying interests of the group into account. Some participants are more interested in REST APIs, for example, whereas others want to focus on JavaScript or Java. People can start each workbook during the allotted session, but then decide to focus only on a particular workbook for further study.
  • Prevent performance anxiety. Some people are quite nervous about taking part in workshops, worrying that they won’t be able to complete the exercises in the allotted time, and won’t be able to meet other people’s expectations or even their own expectations for what they’ll achieve during the workshop.

The first part of each workbook consolidates what participants have learned in earlier lectures. Subsequent parts of the workbook are more advanced.

As an example, here’s the introduction and table of contents for the first workbook:

Workbook table of contents

Part 1 of this workbook consists of material covered in the previous lecture. Parts 2 to 4 contain new material.

Later sessions in the workshop build upon the material in parts 2 to 4 of this workbook, but without assuming that the participant has already had time to complete those parts.

Helping people feel comfortable

For hands-on sessions, I made it clear that people should feel free to pair up with someone. Some people work best alone, getting into the zone and focusing. Others work best with a partner. The partnering worked particularly well during the latest workshop in Washington, DC. A number of people paired up, and the room hummed with concentration.

I also let people know that the workbooks contain everything they need. In particular, all the code is available in the workshop material or via links in the workbooks.

Introducing a hands-on session

I wanted people to enjoy the workshop, to feel they had time to get to know their fellow participants, to come away feeling that they’d learned something useful, and above all to have plenty of material and avenues for further investigation. Judging from the feedback, the design is working well. Thanks to everyone for your comments, and for the suggestions on how to improve the workshop for future incarnations!

Delete or remove?

What’s the difference between delete and remove? When should you use the word “delete” on a user interface or in a document, and when “remove”? Here’s an explanation that makes sense to me.

Use “delete” when you’re getting rid of the thing entirely – when it’s disappearing from the data store. Use “remove” when you’re subtracting it from a group or a list, but it remains available in the data store.

An example is the model of users and groups. Let’s say the user arthurdent belongs to two groups: spacers and earthlings. When Arthur no longer lives on planet Earth, you would remove arthurdent from the earthlings group. But if Arthur has departed the universe without leaving so much as a towel behind, you would delete the username arthurdent.

Here’s another example. Let’s say you have a number of credit card charges, which you’re adding to two expense reports. By mistake, you’ve added one of the charges to Expense Report 1 as well as Expense Report 2.  So you need to remove that charge from the report. In addition, there’s an erroneous credit card charge of zero dollars, which you can delete without adding it to a report.

Delete or remove

Works for me. :) What do you think?


Get every new post delivered to your Inbox.

Join 1,589 other followers

%d bloggers like this: