Sarah Maddox's Blog, page 20

API tech writing workshop comes to New York City

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.

Workshop details

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:

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.

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

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:

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

 

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:

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!

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

Novels and fascinating theories

A while ago,��I stumbled across M Vera B��hrmann���s book, Living in Two Worlds ,��and found it fascinating. My��novel, Things Unseen , grew around the ideas in Dr��B��hrmann���s book.��I wonder how often that happens: an interesting theory in psychology, or archaeology, or another discipline, opens the bud of a romantic novel or wakes the sleeping beast of a horror story.

Dr��B��hrmann spent a number of years working with African healers amongst the Xhosa people in South Africa, exploring the ways in which the healers look after the health of their community. These healers are often called “witch doctors”, and their powers are sometimes referred to as “magic”. Here’s what Dr B��hrmann has to say:

My aim therefore is to show that much of what is called “magic” in the healing systems of the amagqira [the Xhosa word for healers] is not “magical” in the usual sense of the word but is based on sound principles of depth psychology, especially as formulated by Carl Gustav Jung and his followers. The amagqira have not thought out and systematised their methods as is customary in the Western, scientific world. They have, rather, perceived their methods intuitively, and use them in, to us, non-rational ways.

… The “two worlds” I am concerned with are the Western world which is primarily scientific, rational and ego-oriented, and the world of the Black healer and his people, which is primarily intuitive, non-rational or orientated towards the inner world of symbols and images of the collective unconscious.” [Living in Two Worlds, published by Human & Rousseau, 1984, pages 14-15.]

Xhosa traditional healers believe that our ancestors communicate with us via dreams. The word ���ancestor��� has a special meaning to a Xhosa person. An ancestor is a presence in your mind and in your family, who plays a very definite and beneficial role in guiding your actions and guarding you and your people.

Jungian healers believe that our unconscious communicates with our conscious minds via symbols in dreams.

I’ve billed my novel, Things Unseen, as “a combination of sizzling romance, eerie horror, and tense psychological drama”. It’s a love story. It’s also a story of African and European cultures meeting, competing, and merging to produce something new. It’s the result of careful study of African culture, language and stories. It plays with symbols from both African and European cultures.

In her book, Dr B��hrmann describes the similarities between the treatment methods and philosophies of African witchdoctors and Jungian psychologists. My novel weaves a story around this theme.

An interplay between story and theory: I’d guess this is fairly common in science fiction. In fact, the inspiration travels in both directions there. How about other types of fiction – have you seen the sleeping beauty of a story awakened by an interesting theory?

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:

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.

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!

Learn about API technical writing in Washington DC

Are you a technical writer in or around Washington DC? On Friday March 20th, I’m running a full-day workshop on API technical writing. It’s free, and you’re very welcome to attend. There’s free food too!

The workshop is happening under the auspices of the the STC Washington, DC – Baltimore Chapter. The content is the same as that of the workshop��I ran in Mountain View in January, with a few updates based on feedback from participants.

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.

Workshop details

Date: Friday, March 20th, 2015

Time: 9 am to 4 pm

Cost: None. The workshop is given free of charge.

Location: Room: ���The White Space���, 9th Floor, 25 Massachusetts Ave NW, Washington, DC 20001 (map: http://goo.gl/A4FqJ8). A parking garage is connected to the building. To see parking rates and hours, search for the address on the parking locator.

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.

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 signup

The event announcement by the STC Washington, DC – Baltimore Chapter has more details. To register for the workshop, scroll down to the Eventbrite box on that page, or go straight to the Eventbrite registration page.

I’m looking forward to meeting DC technical writers. Hope to see you there!

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.

Works for me. :) What do you think?