Sarah Maddox's Blog, page 24

Talk about API technical writing in Silicon Valley next Monday

I’ll be speaking at the meeting of the STC Silicon Valley Chapter in Santa Clara on Monday 25th August. Thanks to Tom Johnson for organising this get-together! I’m excited to meet the Silicon Valley writers. 

The talk is titled, “API Technical Writing: What, Why, and How“. The meeting announcement has the details.

Have you ever wondered what API technical writers do, and how they go about it? Perhaps you’d like to move into developer-focused documentation yourself, and need some tips on getting started.

Join us to discuss what an API is and poke some easy-to-use APIs that you can play with later yourself. Examine examples of API documentation, pick up a few useful tools, and grab some ideas on getting started in this field. It’s an exciting and rewarding area of technical communication.

Date and time:

August 25th, at 6pm for socialising. The talk starts at around 7pm.

Location: 

IHOP Restaurant

4200 Great America Parkway

Santa Clara, CA 95054-1210

408-980 8887

Lunch-time talk on API technical writing

I’ll be speaking at the lunchtime meeting of the Sydney CBD Technical Writers’ Group on Wednesday 6th August. This group is led by Bede Sunter on behalf of the Australian Society for Technical Communication NSW. The session is free of charge, and open to all. You’re invited! (Please bring your own lunch.)

The talk is titled, “API Technical Writing: What, Why, and How“.

Have you ever wondered what API technical writers do, and how they go about it? Perhaps you’d like to move into developer-focused documentation yourself, and need some tips on getting started.

Join us to discuss what an API is and poke some easy-to-use APIs that you can play with later yourself. Examine examples of API documentation, pick up a few useful tools, and grab some ideas on getting started in this field. It’s an exciting and rewarding area of technical communication.

Date and time: Wednesday 6 August, from 12:30 to 1:30.

Location: 

Level 21, HSBC Building

580 George Street – close to Town Hall Station

Sydney, Australia

Map: http://goo.gl/maps/7UdRH

Offices of TP3 Group

Ask at reception on level 21 for the room number

RSVP: Please add a comment to this page if you’re coming, so that we know how many people to expect over and above the usual crowd. :)

Hobbies and pastimes of technical writers everywhere

Hallo fellow techcomm folks! Do you have a hobby?

Mine is fairly pedestrian. I like to go walking in the bush. It blows away the cobwebs. Well, actually, I often have to blow away the cobwebs myself. They festoon the pathways in the early morning. It’s best to keep your mouth closed when strolling in the Australian bush, or you’ll find yourself spitting spiders.

Sometimes a bird pops out and does something interesting, and I blog about it.

Of a dark winter’s eve I can perchance be found tickling the ivories. Perhaps significantly, other members of the household are usually to be found in the furthest corners of the house.

So fess up

What do you get up to when the pleasures of the pen pall? (Aside from avoiding sentences like that.)

David Farbey bakes bread.
Rhonda Bracey quilts. Magnificently.
Tom Johnson blogs.

For years I had a Calvin and Hobbes cartoon pasted above my desk. It showed Calvin’s father with a mangled bicycle, obviously the result of a bad stack. The caption read: “The secret to enjoying your job is to have a hobby that’s even worse.”

How to build a map using a spreadsheet and JavaScript

This week I published a post on the Google Geo Developers Blog describing the building blocks of Tech Comm on a Map. That post assumes some knowledge of the Google Maps JavaScript API, so I’ve decided to write a top-up post with a little more detail.

Tech Comm on a Map puts technical communication titbits (societies, groups, businesses and conferences) onto an interactive map, together with the data and functionality provided by Google Maps. You can grab a copy of the code from GitHub. The most relevant bits are the HTML that defines the web page (index.html) and the JavaScript that defines and interacts with the map.

Loading the Google Maps JavaScript API

The first thing is to get hold of a map via the Google Maps JavaScript API. An HTML

Now all the functions of the Google Maps JavaScript API are available to the web page, and I can call them from my own JavaScript. With just a few lines of code I get an interactive Google map, loaded with geographical data and offering the default set of user functionality: zoom, pan, the choice of map view or satellite view, and Street View. To get started, see the Google Maps JavaScript API documentation.

You may have noticed the libraries parameter in the above

&libraries=places

I’ve added that parameter to request the Places library, which I use for the search box on the map as described later in this post.

Putting the map into the HTML page

The HTML file contains a element, with an ID, to define a place to put the map. In this case, I’ve called it “map-canvas”.

 

Now the JavaScript can refer to that when inserting the map onto the page. In essence, the JavaScript consists of two sections:

A function, here called “initializeMap()”, that sets up the map options and then adds the map to the page.
A listener that waits until the page has finished loading, then adds the map by calling the “initializeMap()” function.

Below is part of the “initializeMap()” function. It creates the map object, google.maps.Map, passing it the element that will contain the map, and a number of parameters that define the map centre, zoom factor, and other options:

function initializeMap() {
  map = new google.maps.Map(document.getElementById("map-canvas"), {
    center: {lat: 35.55, lng: 16.50},
    zoom: DEFAULT_ZOOM,
    panControl: false,
    streetViewControl: true,
    streetViewControlOptions: {
      position: google.maps.ControlPosition.LEFT_BOTTOM
    },
    zoomControl: true,
    zoomControlOptions: {
      position: google.maps.ControlPosition.LEFT_BOTTOM
    }
  });
}

And this is the listener that calls the function to load the map:

google.maps.event.addDomListener(window, 'load', initializeMap);

Great, now we have a map, and I can start adding the bits and pieces that make up Tech Comm on a Map.
Visualising tech comm data on the map
Tech Comm on a Map  contains information of the following types, all related to technical writing and technical communication:

Conferences (purple circles).
Societies (yellow circles), which includes societies and associations.
Groups (pink circles) for smaller groups and regular meet-ups of technical communicators, either as part of a larger society/association, or as an independent group.
Businesses  (green circles) for commercial organisations specialising in tech comm, such as consultancies, recruiters, publishers, independent technical writers, and so on.
Other (blue circles), a grab bag to catch anything that doesn’t fit into the above categories.

The data is held in a Google Docs spreadsheet. Any changes we make in the spreadsheet are immediately reflected on the map. For details on setting up such a spreadsheet, and pulling the information into the map, see my post on the Google Geo Developers Blog.

The Place Autocomplete search box
The last piece of the puzzle is to let users search for a specific location on the map, so that they can zoom in and see the events in that location. The location search box on the map is provided by the Place Autocomplete widget from the Google Places API.

The HTML defines an input field for the search box:


The JavaScript adds the search box to the page, and creates a listener to react when the user starts typing in the search box:
var input = /** @type {HTMLInputElement} */(
    document.getElementById('place-search'));

var types = document.getElementById('type-selector');
var branding = document.getElementById('branding');
map.controls[google.maps.ControlPosition.TOP_LEFT].push(branding);
map.controls[google.maps.ControlPosition.LEFT_TOP].push(types);
map.controls[google.maps.ControlPosition.TOP_LEFT].push(input);

var autocomplete = new google.maps.places.Autocomplete(input);

// When the user searches for & selects a place, zoom in & add a marker.
var searchMarker = new google.maps.Marker({
  map: map,
  visible: false,
});

autocomplete.addListener('place_changed', function() {
  searchMarker.setVisible(false);
  var place = autocomplete.getPlace();
  if (!place.geometry) {
    return;
  }

  // If the place has a geometry, then show it on the map.
  if (place.geometry.viewport) {
    map.fitBounds(place.geometry.viewport);
  } else {
    map.setCenter(place.geometry.location);
    map.setZoom(AUTO_ZOOM);
  }
  searchMarker.setIcon(/** @type {google.maps.Icon} */({
    url: place.icon,
    size: new google.maps.Size(71, 71),
    origin: new google.maps.Point(0, 0),
    anchor: new google.maps.Point(17, 34),
    scaledSize: new google.maps.Size(35, 35)
  }));
  searchMarker.setPosition(place.geometry.location);
  searchMarker.setVisible(true);
});
What’s next?

Thanks to everyone who has contributed to this project. We’ll continue adding data items to the spreadsheet. We technical communicators are putting ourselves on the map!

As far as the code is concerned, there are already a few ideas for new features:

Add marker clustering, so that it’s easier to read the map when there’s a large number of items in a small area.
Make it possible to share a link to a particular item on the map, for example by creating and storing a hash fragment in the URL.
Add a data type for training/courses.

Would you like to contribute? The code is on GitHub.

Documentation that developers need to do their jobs

A fellow technical writer asked me this week about the documentation that developers need to do their jobs. He was thinking not of the guides people need when they want to integrate their systems with another organisation’s systems, but rather the internal guides developers may write for themselves about their projects and tools.

That’s a very good question. I’ve thought about it over the last couple of days, and pulled together a list of the types of developer-focused documentation I’ve come across. If you have any to add, please do!

The list is confined to documents relating to the role of software engineer/developer. It doesn’t include more general information that all employees need, such as human resources and facilities.

Information about the project and system they’re working on

Who the people are: engineering team members, product managers, technical writers, stakeholders.
Customers: Who they are and what they do, or would like to do, with the system or application that the team is developing.
Goals: Mission, vision, goals for the upcoming month/quarter/year.
Product requirements document for the system, application, or major feature that they’re working on.
Design documents.
Architectural overview, preferably in the form of a diagram.
Comments in the code, written by their fellow developers.

Help with their development environment

How to set  up the development environment for the application/system that the team is developing.
Guides to specific tools, whether built in-house or third party, including the IDE of choice, build tool, source repository.
A pointer to the issue tracker used by the team.
Guide to the team’s code review tool and procedures.
Best practices for writing automated tests, and information about existing code coverage.
Links to the team’s online chat room, useful email groups, and other communication tools used by the team.
Where to go with technical and tooling problems.

Coding guides

Coding style guides for each programming language in use.
Guidelines for in-code comments: style; where to put them; how long they should be; the difference between simple comments and those that are intended for automated doc generation such as Javadoc; and encouragement that comments in the code are a Good Thing.
Best practices for code readability.

Sundry useful guides

Communication guidelines, if the developer’s role will involve significant liaison with third-party developers, customers, or important stakeholders.
A map to the nearest coffee machine, preferably reinforced by a path of glowing floor lights.

Too much information can be a bad thing. :) I spotted this sign on a recent trip to Arizona:

How to stop your map from jumping around when info windows open – Google Maps JavaScript API

By default when an info window pops up on a map created with the Google Maps JavaScript API, the map pans automatically to ensure that the entire content of the info window is visible. If your map has a large number of markers that provide info windows on hover, this auto-panning can be quite disturbing for the user.

TL;DR: To disable the automatic movement of the map, set disableAutoPan to true in the properties on infoWindowOptions. See the documentation.

The automatic movement of the map, called auto-panning, can be very useful in some situations. It’s good to make sure people can see all the content of an info window without having to scroll the map themselves.

On the other hand, let’s say you have a large number of markers on the map, and have added some JavaScript to make an info window open each time the cursor moves over a marker. If auto-panning is enabled, the map can jig around as the cursor moves across it, repositioning the map each time an info window pops up. This can be quite disconcerting for the user.

My Tech Comm on a Map project suffered from that problem, until I disabled auto panning:

var infoWindow = new google.maps.InfoWindow({
  pixelOffset: new google.maps.Size(0, -10),
  disableAutoPan: true
});

The full code is on GitHub.

Tech Comm on a Map now includes businesses and groups

A month ago I announced my project called “Tech Comm on a Map”. The idea is to help us see what’s happening in the world of technical communication around the globe. Tech Comm on a Map puts tech comm titbits onto an interactive map, together with the data and functionality provided by Google Maps.

When first announced, the map included data types for conferences, societies, and a grab-bag called “other“, which currently contains a couple of historically-interesting morsels.

Now I’ve added two more data types:

businesses for commercial organisations specialising in tech comm, such as consultancies, recruiters, publishers, independent technical writers, and so on.
groups for smaller groups and regular meetups of technical communicators, either as part of a larger society/association, or as an independent group.

Any groups or businesses to add?

At this point there are very few businesses and groups on the map. Do you have one you’d like me to add? Please add a comment to this post, including the following information for each item. The information will be publicly available on the map, via an information box that appears when someone clicks on the relevant circle on the map:

Type: Conference, Society, Business, or Group
Name of the business, group, society or conference.
Description.
Website address (or an email address that people can use to get more information).
Street address (this is essential, to position the item on the map).
Start and end date for conferences, or meetup timing for groups (e.g. “First Wednesday of every month at lunch time”, or “Every Tuesday at 7pm”).

Note: Don’t add the names or addresses of any individuals, unless it’s your own name and address. We need to ensure we have people’s permission before adding their information in a comment on this post, or on the map. Any information you add here should be already publicly available on an organisation’s website or other publication.

Contributors to the project

Thanks to the following people who have helped me add data to the map so far: Sarah O’Keefe, Ellis Pratt, Stefan Eike.

Thanks also to Stefan Eike and Stephen Farrar, who have both contributed to the code on GitHub.

More coming

Excited? I am. :) If you’d like to know more about the project, check out the introductory blog post. Soon I’ll write another post with the technical details of the APIs and other tools involved. In the meantime, here’s Tech Comm on a Map.

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:

7 Archetypes of Video Storytelling
Patient Education and Health Literacy
The Making of “The Language of Content Strategy”
Information Architecture Bottom Up
Minimalism
Google Glass and Augmented Reality
API technical writing (This was my presentation)
Key Trends in Mobile Publishing
How technical writers can build personal influence
Content strategy versus wicked ambiguity

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:

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:

Overcoming the monster. David and Goliath, good versus evil, nature versus machine.
The rebirth, revival, renaissance.
The question. A mission to change things for the better.
The journey, or the return. Moving from one idea to another, or growth.
Rags to riches. Overcoming adversity or poverty.
Tragedy. An unhappy ending, or a twist that you don’t expect, almost always involving the main character.
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:

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!