Author Archives: Sarah Maddox

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

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?

Things Unseen

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!

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

Screen Shot 2015-02-21 at 6.10.38 am

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?

Follow

Get every new post delivered to your Inbox.

Join 1,579 other followers

%d bloggers like this: