Blog Archives

Workshop on API technical writing

I’m excited and delighted to announce that I’ll be presenting a one-day workshop on API technical writing, in conjunction with the Silicon Valley Chapter of the STC (Society for Technical Communication). 

The workshop will be 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 will be on APIs themselves as well as on documentation, since technical writers need to be able to understand and use a product before we can document it.

Date: Friday, January 23rd, 2015

Time: 9 am to 4 pm

Location: 1295 Charleston Rd, Mountain View, CA 94043 (Google Maps: The building is on the Google campus. The workshop takes place in the “Araujo Tech Talk” room on level 1.

Cost: None. The course is given free of charge, sponsored by Google and the STC Silicon Valley Chapter.


  • STC membership is not required.
  • The course is currently fully subscribed. But it’s worth adding your name to the waiting list, in case a place becomes available closer to the date. We’ll check the number of tickets and the waiting list early in January.
  • If you’ve registered but later find you’re unable to attend, you can cancel your order in EventBrite. This will open up a place for people who are on the waiting list.

Workshop description

The course will include the following sessions:

  • Lecture: Introduction to APIs, including a demo of some REST and JavaScript APIs.
  • Hands-on: Play with a REST API and a JavaScript API.
  • Lecture: JavaScript essentials.
  • Hands-on: Use JavaScript to exercise the sample JavaScript API in a more in-depth manner.
  • Lecture: The components of API documentation.
  • Hands-on: Generate reference documentation using Javadoc.
  • Lecture: Beyond Javadoc – other doc generation tools.

Details and signup

For details of food, what to bring, prerequisites, and how to sign up via EventBrite, please head on over to the STC Silicon Valley workshop page.


Here’s some information about parking near 1295 Charleston Rd, Mountain View (Google Maps:

  • There are several parking lots next to building 1295. You can park in any unmarked spot. Avoid spots that are marked for expectant mothers or other special requirements.
  • If parking immediately near building 1295 is full, you can park in the lots near building SB50 (1350 Shorebird Way):
  • You can also make use of the valet parking between 1245 & 1225 Charleston Rd.

Questions and comments

Please let me know if you have any questions or comments.

WritersUA 2011 Monday – Design and tools for eLearning

This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. These are my notes from the session called “Determining the Best Design Approaches and Development Tools for eLearning” presented by Joe Ganci. If you find any inaccuracies, they’ll be mine.

Joe’s presentation style is conversational, easy and comfortable. He walks right up to the audience, asks them questions and tells them personal anecdotes to illustrate his points.

First points to consider

There are four things to consider when determining your design approaches and your choice of development tools for an eLearning system:

  • Talent – Who is your talent? Who does the work?
  • Topic – What do you want to teach people, and who is your audience?
  • Technique – What technique are you going to use to impart your information?
  • Tool – Determine the tool or tools after all the other questions are answered.

For the rest of the session, Joe dived deep into each of the above points, and showed how your choices will influence the tools that you choose.


Who does the work? Consider these three groups of people:

  • Instructional designers
  • Subject matter experts (SMEs)
  • Programmers

At the beginning of a project, the instructional designer creates a number of deliverables, including the storyboard, design document and analysis document.

Subject matter experts are well known to technical writers.

When considering the programmers, ask these questions: Who builds the eLearning in your organisation, and who should it be?

How does talent impact tool selection? SMEs, instructional designers and programmers will be using different tools. Joe showed us how the different groups of people are comfortable with different tools. For example, SMEs may use presentation tools like PowerPoint, instructional designers may use Camtasia, programmers use things like XML, HTML, Flash.


Looking at the information you want to impart, there are four key areas:

  • Information (concepts)
  • Compliance
  • Technical information
  • Soft skills (highly scenario-based)

Questions to ask yourself: Which of those information types are the most requested within your organisation, and who works on them?

How does topic impact tool selection? For informational topics, presentation tools like PowerPoint and Prezi are useful. For compliance topics, you may choose Camtasia or Lectora. For technical information, something like Raptivity, SmartBuilder. For the soft skills, you need a lot of computing: XML, HTML, Flash.


Joe discussed four kinds of technique in eLearning systems:

  • Tell me
  • Show me
  • Let me
  • Test me

Moving from top to bottom of the list, these techniques require an increasing level of complexity in the instructional design.

Questions to ask: What techniques are your favourite for eLearning, and which techniques do you want to implement next.

One of the audience members said he prefers a combination of “show me” and “let me”. Joe agreed. You don’t want to overdo the “let me” side of things.

It’s sometimes a good idea to be able to present each candidate with a slightly different experience.

When testing the student, one technique is to set up a pool of questions, and have Captivate randomly select questions out of the pool. You can base the pools on level of complexity, to ensure that each candidate gets the same overall level of test.

Essential questions for determining your design approach

Joe took us through each of the following questions that we need to ask, and discussed the various options for each.

  1. What is the content? (Your objectives, lesson plan, time available to the learner, existing content that you can base yours on.)
  2. Who is the audience? (Age, prerequisite knowledge, language, culture, disabilities, educational level, and so on.)
  3. How will you design the material? (Rapid prototyping, or the traditional instructional design approach, or a combination of the two.)
  4. What is necessary for the design? (How much time is necessary, do you need a video, do you need audio, how much text is required, how much interactivity, and so on. A number of the answers depend on you audience as well as the topic. The answers to these questions affect your choice of tool.)

How does technique affect tool selection? For “tell me”, the presentation tools like PowerPoint are effective. For “show me” and “test me”, you may use Smartbuilder and similar tools. For “let me”, you will need HTML, XML, Flash, and so on.

Questions to consider: What tools are available to your organisation, and what tools do you know? You need to consider also how well you know a tool, and whether you know everything that you need to know.

The tools

There are a number of tools, and many of them do similar things. But they don’t all work the same way. There are some really good surveys out there. Joe pointed out the survey of the Top 100 Tools for Learning 2010.

Interestingly, the tools at the top of the list are things like Twitter, YouTube, GoogleDocs – social and informal learning tools.

As a trend in the next 3 years, Joe sees more and more hand-held platforms.

How does all this affect developers of eLearning?

We will be basing our work on the known foundations, but we’ll be looking at new ideas and techniques too.

An example of eLearning developed by Joe

Joe showed us an eLearning tool that he created in Captivate. It’s aim is to train hotel clerks in dealing with conflict. It’s available on the web: Hotel Clerk Training, Dealing with Conflicts. (Make sure you have audio enabled on your computer.)

It’s pretty cool. You can hover over each person, such as the manager or coworker, to see what each person says when you (the clerk) ask them what to do.

There’s a bit of humour in it, especially in the acting on the video segments – enough humour to make you smile, and enough to make you sympathise with the people.

When the user chooses the right response, the system responds with some jubilant animation to reward them.

Why is this type of approach better than PowerPoint? The student who is already an expert can fly right through the lesson without wasting time. A novice can explore all the answers in full. It’s also more interesting and more engaging. An experience as close to real life as possible is more likely to put the learning into your long term memory, as opposed to short term memory.

My conclusion

Thank you Joe for an interesting and engaging approach to the choice of tools for eLearning. It’s very useful to see how our decisions can affect the tools we choose, and how indeed we should make other decisions before deciding on a tool. I love the hotel clerk training tool!

AODC day 3 – Content, standards, learning and SCORM

Last week I attended the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. This blog post is part of a series about some of the AODC sessions I attended.

Here are some notes I took from the session on content, standards, learning and SCORM, by Allyn Radford of Learn’ilities’. I hope these notes are useful to people who couldn’t be at the conference this year.

Content, Standards, Learning and SCORM

Allyn started by giving us some context of what is happening right now. Within content domains, the key themes of the information age are being adopted: Modularisation, specialisation, integration and interoperability. Our communication is changing in volume, purpose and channels. The emphasis is more on collaboration and less on expert-to-novice teaching. And there’s a stronger emphasis on openness.

Allyn says we need to rethink the focus of reusability. Now we have to reuse content across disciplines, and we have to assume that the content’s destination is unknown.

Everything is 2.0 and everything is social. We are living in a mash-up world. As an illustration, Allyn walked us through parts of Mashable, The Social Media Guide. It’s like a directory of mash-up sites that combine different data sources to produce some interesting conclusions, statistics and visualisations. One of Allyn’s favourites is the fun mash-up called If I dig a very big hole, where will I end up?

What are the implications for learning systems?

We are looking at moving from monolithic learning applications to modular services, across different sources and services.

Learning content and organisational content should no longer be seen as two separate things. Marketing information, specifications, etc, can also be used in learning material or in brochures. So you start to develop a whole different appreciation of how you determine the value of content in your organisation.

Content is one of the most expensive things an organisation will create, compared to the technology systems that support that content.

There has to be a bi-directional relationship between three key things: The content, the process/practice used to create the content, and the technology infrastructure. Before you create content, you need to set up procedures for how that content will be maintained in the future.

What’s the role of standards in all this?

Interoperability, reuseability, maintainability — all the “ilities”. (Hence the name of Allyn’s company.)

Management of content is key. Traditionally in learning systems, not enough effort has been put into this.

Allyn showed us a list of standards related to LET (Learning, Education and Training). One of them is SCORM (Shareable Content Object Reference Model). Allyn listed these 6 key concepts that SCORM was designed to support:

  • Interoperability
  • Accessibility (different devices and locations, as needed)
  • Reusability
  • Durability (content must outlast changes in technology)
  • Maintainability
  • Adaptability

SCORM allows you to take courses from one learning system, where they were developed, and put them into other learning systems where required.

Granularity and reusability are interrelated. You need to consider reuse versus context. You lose context as your content become more granular. So you have to find the best mix for your environment, depending how important context is to you.

Allyn says that the problem with most existing standards is a “walled garden” attitude. This does not work well with the move towards open standards. There are significant costs to development and adoption of standards.  The “no-strings-attached” licensing is essential in LET standards.

Allyn works primarily with LETSI at the moment. The LETSI model is very open. LETSI does not develop standards, but works towards the adoption of available standards in learning technology and related fields like HR and Knowledge Management. It focuses on the interstitial work i.e. the bits that need to happen between the existing systems.

LETSI was asked to look at what “SCORM 2.0” might look like, focusing on interoperability. They started reconceptualising what was actually happening, in the areas of learning activities, resources, people and competency frameworks. It turns out that SCORM 2.0 is nothing like previous versions of SCORM.

Nowadays, people in universities and schools are not locked into a particular learning management system. They’re using podcasts, the web, and a number of other tools. Part of what’s needed, says Allyn, is to implement software that coordinates the bits of content used.

  • A new solution for content orchestration (sequencing of content, e.g. based on how the learner performs).
  • Integration of training with policy or technical documents. Also integration of data for learning and non-learning purposes, and integration of social learning content.
  • Integration with HR, SIS and enterprise standards (so that we know what type of learning the person needs, to do the job required).
  • Incorporation of competency models.
  • Support for new pedagogies (such as collaboration).

So a new infrastructure model may have a set of “resources” that are data stores such as published content, user information systems, competency store, and so on. Users will access the stores via portal interfaces and portal applications. It’s the mash-up idea. There will also be an external integration layer, to allow access to external content sources.

Open educational resources

We must differentiate between “open education” and “open educational resources”:

  • “Open education” is the provision of educational experiences with few, if any, barriers to participation and often no cost.
  • “Open educational resources” (OERs) are resources that can be used in learning under some form of open licence governing usage and adaptation. So you can include the open courseware into your learning system.

OERs improve access to educational content, e.g. in third-world countries like Africa. The aim is to reduce cost (text books are very expensive) and to improve quality (by pooling the knowledge of experts and taking the content that’s most relevant to your environment). This can be bad news to publishers of learning materials.

OERs are built to be reused, so that you can adapt and remix them to suit your needs. So it’s very interesting to look at OERs to see what’s happening with open learning at the moment.

Allyn emphasised that we need to have a structured content model in learning content, to support granularity (essential for content reuse) and interoperability (essential for mixing content).

One big problem at the moment is the editing and aggregation tools available. Allyn has used and reviewed a number of tools and has not found a satisfactory one yet.

XML is the appropriate format to support content and structure, ignoring presentation. Useful formats are CNXML (an open education resource format), DITA and others.

What can you do?

Next steps, particularly when considering co-operation between creators of technical documentation and creators of learning materials:

  • Participate in common activities (e.g. LETSI).
  • Be aware that your content may be used in ways and places you don’t know about.
  • Write for broader reuse scenarios.
  • Have a joint focus on reuse and interoperability.

Question time

Comment from the floor: “I don’t think it’s possible to re-use content. A lot of speakers at this conference have talked about it, but I don’t think it’s possible.”

Answer: Granularity is the key. Identify the content that is suitable for reuse. There’s no intention to reuse all content. When you write content in a narrative form, you are tied to writing in a particular way. But when you write structured, granular content, you’re not thinking about the presentation or where it’s going to be used. You concentrate on the content itself. That makes the content more reusable (where applicable).

Thank you Allyn for a very interesting presentation.

Decomposing the Handbook for the Recently Deceased (from the movie Beetlejuice)

When I saw the film Beetlejuice recently, it struck me that a technical writer must have played a big part in, and had a lot of fun with, the scenes involving the Handbook for the Recently Deceased. So let’s pay tribute to this unsung hero, this spectral tech writer extraordinaire.

Decomposing the Handbook for the Recently Deceased

Decomposing the Handbook for the Recently Deceased

Image from the film Beetlejuice.

Technical writing is often accused of being deadly 😉 dull. Is there a grain of truth in that, and how can we liven it up a bit?

A rewarding task for trainee technical writers could be to analyse the Handbook for the Recently Deceased. You could even concoct a useful interview question when you’re looking to hire a technical writer:

Have you seen the film Beetlejuice?
Uh, yes.
Tell us what was wrong with the Handbook for the Recently Deceased.

If the interviewee isn’t flummoxed, they’re bound to be a useful technical writer, or at least crazy enough to be one.

In the spirit 😉 of simplicity

Simplicity, clarity and structure are of grave 😉 concern to technical writers. If our readers are to have the ghost of a chance of understanding our documents, we need to take care with every word.

Two other bloggers are dead right when they say:

Task 1: Analysing the Handbook

In the film Beetlejuice, when Barbara and Adam first see the the Handbook for the Recently Deceased, Barbara says, “You know what? I don’t think we survived the crash.”

[So it seems that’s one thing the Handbook got right. The title gave them a clue about their current state. But wait. Adam misreads the title as “Handbook for the Recently Diseased.” The title could use simpler words and give more of a hint about the sort of information the book contains.]

Now Adam is reading while Barbara is pacing up and down, chewing her nails and looking very worried. She says, “I hate this. Just… Can you give me the basics?”

[There’s no Quick Start Guide.]

Adam replies, “This book isn’t arranged that way. What do you want to know?”

[The structure of the book doesn’t help these poor lost souls find the information they need.]

Barbara shoots a volley of questions. “Well, why did you disappear when you stepped off the porch? Are we half way to heaven or half way to hell? And how long is this going to last?”

[Hey tech writer, an FAQ section would be helpful. There are some other obvious candidates here: Where am I? What am I? Where are all the other dead people?]

Adam goes on, “I don’t see anything about heaven or hell. This book reads like stereo instructions. Listen to this:

Geographical and temporal perimeters: Functional parameters vary from manifestation to manifestation.

[That’s as clear as mud! Know your reader and use simple language, or at least define your terms up front, so that Barbara and Adam know that they are “manifestations” now.]

Understandably, Barbara and Adam are a bit dispirited. Still, they keep trying. Adam keeps paging through the book, and Barbara carries it around with her.

[Everyone knows the value of documentation.]

At last our heroes’ perseverance starts paying off. A family of living people moves into Barbara and Adam’s house and start re-building it. Our heroes dislike the new inhabitants and hate what they’re doing to their home. Barbara says, “What are we going to do?”

Adam says, “We’re not completely helpless, Barbara. I’ve been reading that book and there’s a word for people in our situation. Ghosts!” He grins with triumph.

[Go, tech writer, go. The book is coming into its own at last. It is giving the reader some useful terminology, and correctly targeting its audience.]

But it’s a painfully slow learning task. Barbara and Adam try some hair-raising (literally) tricks, but in vain, because the living can’t see them. Meanwhile, re-construction of the house is steaming ahead and chaos is merrily ensuing. They gaze out of the attic window, still clutching the book. Barbara says, “Isn’t there an index or something?”

[Yes, where is the index?]

At last, just when things are at their worst, Adam remembers something. “We need some help. I read something in this book this morning:

Emergencies: In case of emergency, draw a door.”

[A trouble-shooting section comes in handy.]

Barbara is by now totally disillusioned. “‘Draw a door’? I don’t know why we keep looking in that stupid book!”

But Adam picks up a piece of chalk and draws the shape of a door on the wall. Nothing happens. He looks in the book again, and finds more instructions. “Aha! Knock three times!”

[Step-by-step instructions, clearly demarcated in a block of text, would have worked wonders here.]

Adam knocks three times on the wall and a door opens, leading them into a weird way-station. But alas, all is not yet sweetness and light. They find a desk marked “Information”. But they don’t have an appointment, because they didn’t know they needed one nor how to make one.

[The Handbook should have a section on contacts and support.]

There’s more. Watch the film 🙂

Task 2: Rewriting the Handbook

Now let’s ask our trainee technical writer to describe how they would go about re-writing the Handbook. First, they would map out a new structure for the book and create a skeleton document. I’ll leave the rest to your imagination.
Decomposing the Handbook for the Recently Deceased

Drawing by Ryan.

For those haunted by a grammatical niggle

Did you wonder, when you saw the title of this blog post, whether “decompose” is a transitive verb? If you did, then:
(a) you’re (well on the way to being) a technical writer, and
(b) you’ll be delighted to know that it is. I looked it up in the Concise Oxford English Dictionary.

How many truly ghastly puns did you stumble across when reading this post? If you found close to ten of them, or even all eleven, then:
(a) you have a morbid fascination with death, or
(b) you have a morbid fascination with puns, or
(c) you’re (well on the way to being) a technical writer 🙂

Any more technical writers in literature or film?

Zen and the Art of Motor Cycle Maintenance, by Robert M Pirsig, could be called a handbook for technical writers, and much more. Does anyone know of any other technical writers or technical writing in literature and film?

%d bloggers like this: