Category Archives: STC

Follow-up on yesterday’s talk about API technical writing

Yesterday I was privileged and delighted to speak at a meeting of the STC Silicon Valley Chapter in Santa Clara. Thanks so much to Tom Johnson and David Hovey for organising the meeting, and thank you too to all the attendees. It was a lovely experience, with a warm, enthusiastic and inspiring audience. This post includes some links for people who’d like to continue playing with the APIs we saw last night and delving deeper into the world of API documentation.

The presentation is on SlideShare: API Technical Writing: What, Why and How. (Note that last night’s presentation didn’t include slide 51.) The slides include a number of links to further information.

The presentation is a technical writer’s introduction to APIs (Application Programming Interfaces) and to the world of API documentation. I hope it’s useful to writers who’ve had very little exposure to APIs, as well as to those who’ve played with APIs a bit and want to learn about the life of an API technical writer.

Overview

Here’s a summary of the presentation:

  • Introduction to the role of API technical writer.
  • Overview of the types of developer products we may be asked to document, including APIs (application programming interfaces), SDKs (software development kits), and other developer frameworks.
  • What an API is and who uses them.
  • Examples of APIs that are easy to play with: Flickr, Google Maps JavaScript API
  • Types of API (including Web APIs like REST or SOAP, and library-based APIs like JavaScript or Java classes).
  • A day in the life of an API technical writer—what we do, in detail.
  • Examples of good and popular API documentation.
  • The components of API documentation.
  • Useful tools.
  • How to become an API tech writer—tips on getting started.

Demo of the Flickr API

During the session, I did a live demo of the Flickr API. If you’d like to play with this API yourself, take a look at the Flickr Developer Guide (and later the Flickr API reference documentation). You’ll need a Flickr API key, which is quick and easy to get. Slide 23 in my presentation shows the URL for a simple request to the Flickr API.

Demo of the Google Maps JavaScript API

My second demo showed an interactive Google map, embedded into a web page with just a few lines of HTML, CSS and JavaScript. I used the Google Maps JavaScript API. If you’d like to try it yourself, follow the getting started guide in Google’s documentation. You’re welcome to start by copying my code. It’s on Bitbucket: HelloMaps.HTML. That code is what you’ll find on slide 28 in the presentation.

More links

There are more links to follow in the presentation itself: API Technical Writing: What, Why and How. I hope you enjoy playing with some APIs and learning about the life of an API technical writer!

STC Summit 2014 wrapup (stc14)

This week I attended STC Summit 2014, the annual conference of the Society for Technical Communication. This year the conference took place in Phoenix, Arizona. The temperature was 40 degrees Centigrade (over 100 F) when I arrived. Phew!

Hot temps outside, hot topics inside. The conference started with two days of workshops, followed by three days of lectures and learning sessions. There were 7 time slots each day, with as many as 20 tracks running simultaneously. So, plenty of sessions to attend, plenty of topics to take in, and plenty of people to meet. I feel as if I haven’t stopped moving since I touched down in Phoenix on Sunday morning.

The sessions

I blogged about most of the sessions I attended. There were two more where it was just not practical to take notes. One was a series of 5-minute lightning talks, very entertaining, but too fast to do justice with notes. The other session took place just before my own, and I was very busy trying to still my nerves and get in the zone, so I didn’t even try to take notes.

Here are my write-ups, in reverse chronological order:

For a full list of sessions, visit the conference site on Lanyrd.

Any more write-ups?

The STC’s Notebook has some information about the conference, as well as about the STC in general.

If you spot any more posts about the conference, please would you add a comment to this post? I’d love to read them.

Thanks and kudos

A huge vote of thanks to the STC Summit committee and all the people who took part in making this such a great event. From my viewpoint as speaker and attendee, the organisation was flawless. The Phoenix Chapter of the STC  put on a big welcome, and put in a huge amount of work behind the scenes to make everything flow smoothly. It was a lovely experience from start to finish.

Thanks also to all the speakers, who put so much work into their presentations. And to the attendees, without whom the conference would be so much the poorer. It was a great pleasure to meet old acquaintances and to make so many new ones too.

I took this photo in the Desert Botanical Gardens in Phoenix:

Desert Botanical Garden in Phoenix

7 Archetypes of Video Storytelling (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

This session promises to offer The Content Wrangler at his best: Scott Abel on “The Power of Emotion: The Seven Archetypes of Video Storytelling”.

From Scott:

We’re wired for stories. Human beings are designed to consume stories. It’s how we understand things.

Stories are an art form. They’re often performed, and it’s the emotion in the story that makes us remember them.

Seven recurring themes

Scott showed us examples videos that harness the 7 recurring themes or story archetypes:

  1. Overcoming the monster. David and Goliath, good versus evil, nature versus machine.
  2. The rebirth, revival, renaissance.
  3. The question. A mission to change things for the better.
  4. The journey, or the return. Moving from one idea to another, or growth.
  5. Rags to riches. Overcoming adversity or poverty.
  6. Tragedy. An unhappy ending, or a twist that you don’t expect, almost always involving the main character.
  7. Comedy. Humour, sometimes with a little satire.

We also saw a cute hybrid: a musical comedy

Transmedia

Scott says we need to think about how we’re going to tell stories in our new world of interconnectedness. Send out our message on all channels – the omni-channel approach.

See the retelling of Cinderella in the video below: “Transmedia Storytelling” – liquid content that’s adaptable for distributing to different media. A different way of telling stories altogether.

Cinderella 2.0: Transmedia Storytelling

Don’t be afraid to use emotion to engage your audience!

Thanks Scott

This was a cute, amusing and engaging session. :)

Patient Education and Health Literacy (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

This session appeals to me as something a little different. Corinne Renguette discusses “Patient Education and Health Literacy: Examining Interview Discourse”. Corinne is from the Indiana University-Purdue University Indianapolis.

In particular, I’m interested in this bullet point from her session summary:

[Attendees will] understand more about issues in patient education and informed consent and the benefits of collaboration in this interdisciplinary field.

Background and definitions

Corinne’s session is about a collaboration between academia and industry, which she feels is interesting to technical communicators.

The aim of the study is to focus on the learner (patient), looking at the language the patients use when they’re discussing a particular procedure, both before and after using the learning materials. The subject matter was obesity and bariatric surgery.

The patient education materials were multimodal.

Corinne talked about the complex terms used in the study, and defined some of them for us. One of the terms is Body Mass Index (BMI) as used to define obesity. The participants in this study had been classified as severely obese, and had high risk of morbidity (death) due to their obesity.

Another term is “health literacy”: The word literacy has a complex definition. You need to define the difference between acquisition (gaining knowledge without conscious learning) and learning (gaining conscious knowledge through teaching).

In the US, over 90 million people have limited health literacy, meaning that they don’t understand basic health information. This results in poor patient health outcomes. Patients need to be able to read and understand health literature, and also be able to make decisions and act upon them.

An example is filling out informed consent forms. Bariatric surgery is major surgery and can have a big effect on someone’s future.

Theoretical framework

It’s hard to measure what someone has learned. Often you have to use a test or questionnaire. In this case, Corinne looked at the language people used after doing the learning.

Because of the combined disciplines in this study, Corinne used a blended theoretical framework to see if the learning objectives were met. She discussed the specific theories used. I took this screenshot of her slide:

stc14

Assessing the outcomes

Corinne looked at the interview discourse. The assumption was the the patients’ answers showed their ability to recognise and recall the information about bariatric surgery.

Methodology

The clinic selected a representative sample of people who would normally be offered the surgery. Corinne coded the pre-test and post-test answers to judge the improvement. For example, she used a plus sign to mean an improvement, a minus sign for a deterioration in the response, and an equals sign if the response was of the same quality.

The entire study happened during the same day. The same questions were asked in the pre-test and the post-test sessions. The test group and the control group had the same questions.

Results

These were the results as shown in the post-test versus pre-test answers:

  • 52% of the test participants gave improved answers.
  • 23% of the control group gave improved answers.
  • More than half of the test participants improved their answers in 53% of the questions.
  • More than half of the control group improved their answers in 16% of the questions.

Corinne now showed us some detailed responses from three of the questions. This was very interesting. For example, we saw new technical vocabulary and lengthier procedural information in the post-test answers. People might struggle with the exact terms, but clearly had a more specific knowledge of the procedure that would be performed on them (the bariatric surgery). When asked how much water you should drink after your surgery, the test group showed a 94% improvement, while 0% improved their answer in the control group. This is an important result for post-surgery health.

Conclusions and ideas for more studies

The test groups shows consistently better results. The multimodal educational materials may have helped to mediate the learning processes. More studies are required, because this was a small control group.

Other studies could add social elements such as study groups, online chats, and experiential learning projects in the classroom.

Corinne pointed out that we, as technical communicators, could ask ourselves how we could work on a partnership to test our communicational materials and what types of collaboration could be useful to us.

Thanks Corinne

I didn’t have time to take notes from everything Corinne said. This was a fast-paced and interesting session, offering a glimpse into the world of academic studies. Thanks Corinne!

The Making of “The Language of Content Strategy” (stc14)

This week I’m attending STC Summit 2014, the annual conference of the Society for Technical Communication. Where feasible, I’ll take notes from the sessions I attend, and share them on this blog. All credit goes to the presenters, and any mistakes are mine.

The Language of Content Strategy is a book by Scott Abel and Rahel Anne BailieIn this session at STC Summit 2014, Scott Abel discussed the content strategy, tools and technologies behind the making of the book.

Problem statement

Time, money, skills and experience are in short supply. Hand-crafting content is expensive, time consuming and not scalable.

The demands of the audience are changing. People use social media, rather than going to a specific website to gather information.

To meet the demands of content delivery today, we need to adopt manufacturing principles. The is made possible by content engineering: The application of engineering discipline to the design and delivery of content.

Case study: The making of  The Language of Content Strategy

In this session, Scott will show us how he and Rahel created a book, an eBook, a website, and a set of learning materials, from a single source, without breaking the bank. They did it by harnessing technology and crowd sourcing.

Scott talked about the differences in approach between technologists and editorialists. Conflict and time wasting arise because of a lack of a common language. Rahel and Scott wanted to craft a solution: A crowd-sourced book about content strategy that is both a case study in content engineering and a practical example of content marketing.

Setting up

The team started with careful analysis of the educational landscape, contributors, and more. Then they defined the content types they needed.

  • The smallest unit of content they would create would be a term and definition pair.
  • Another content type is an essay of 250 words.
  • Then there are contributor bios, statements of importance, and resources.

For the authoring environment, the team selected Atlassian Confluence. It’s a wiki with support for XML content re-use.

They also chose a gimmick: 52. The project included 52 terms, 52 definitions, by 52 experts, published over 52 weeks, and one of the output formats was 52 cards.

Then they selected a team of experts: the best and brightest in tangentially-related fields.

Other roles and responsibilities: markup specialist, editor, indexer, peer reviewers, and a graphic artist.

The source data

The source was authored in Confluence wiki. The content types are clearly labelled: Biography, importance statement, topic name, definition, etc.

The output

In the various output formats, the content is structured differently but still consists of the various topic types. For example, in the printed book every chapter is two pages long, and consistently structured. The eBook format is slightly different, as are the website format and the flash cards learning format.

Each Thursday, one chapter is automatically published. The web output also contains audio files, photos, and additional resources that are not contained in the book.

The advantages of a future-proofed content strategy

The team was able to add content after the fact, such as the audio files for accessibility. The content strategy was designed to future proof the content, so the team was able to adjust to challenges and opportunities. And the strategy is repeatable. Now that it’s been done, it can be done again.

Scott told an amusing story of how he disobeyed his own rules, and tried to create another channel by copying and pasting instead of using the single-sourced content. A marketing person asked him to create a slide deck from the content. He was on a plane, without WiFi, so decided to do it by cutting and pasting. Needless to say, this didn’t work. By the end of the flight he had only 13 slides of the required 52, and had run out of laptop battery!

Cost

The cost of the project came in at under $10,000USD.

  • Approximately $4000USD forgraphic design, indexing, editing, markup assistance, audio tracks and hosting, the URL for the first year, and site hosting for a year.
  • Approximately $5,440 for book donations, postage, Adobe InDesign, Confluence Wiki, and overhead/administrative costs.

Scott’s promise

Scott finished by saying that if you want to undertake a similar project, ask him. He will try to help.

This was a fun and inspiring talk. Thanks Scott!

Follow

Get every new post delivered to your Inbox.

Join 1,488 other followers

%d bloggers like this: