Blog Archives

Talking about APIs and Maps at STC Summit 2017

I’m excited to be speaking soon at STC Summit 2017, the annual conference of the Society for Technical Communication. The event happens in Washington, DC, on 7-10 May. My presentation is about APIs, maps, developers, and a tech writer’s foray into the world of app development.

The conference theme is “gaining the edge”. So I decided to talk about my experiences developing an app, and why I tried my hand at app development. The app, Tech Comm on a Map, is an interactive web-based map that shows events of interest to technical communicators.

In this presentation, you’ll see some code and understand the nuts and bolts of the app – where the data is stored, how it gets there, how it ends up on a map for everyone to see.

Follow me on a tech writer’s odyssey into app development.
Tread in dangerous territory.
We may even see a dragon or two.
Emerge a little triumphant, and certainly well travelled.

Q: Why does the journey on this map start in Sydney and end up on the east coast of the US?
A: Because that’s the trip I’ll make to give this presentation at STC Summit. 🙂

At this session, you’ll learn the technical details:

  • The nuts and bolts of a web-based application like Tech Comm on a Map: where it’s hosted, where the data is stored, the JavaScript code and the APIs that create the map and the app’s functionality.
  • How the app’s data is crowd sourced.
  • What open sourcing your code means, and why you may want to do it.
  • The difference between a web-based application and a mobile app. Tech Comm on a Map is available as a native Android app as well as a webapp.
  • The information sources that I used when developing the app.

You’ll also see how such a project can help develop your soft skills:

  • My engineering colleagues helped me kick off the development of the app, and made ongoing suggestions for refinement. The resulting interactions increased mutual understanding and respect.
  • Fellow technical writers all over the world help compile the data. A project like this is a good way of connecting with your peers.
  • Developing an app can help you better understand your subject and your audience of software engineers and other specialists.
  • Such a project gives you confidence in your own abilities, even if you’re just skimming the surface of code complexity.

Here’s the session on the STC Summit schedule: A tech writer, a map, and an app.

You can also read more about the app, Tech Comm on a Map.

Advertisements

Tech comm 2015 now on the map

Tech Comm on a Map now displays all the 2015 technical communication conferences that I’ve found so far. Take a look, and let me know if there are any more tech comm conferences, groups, businesses or societies to add.

Tech Comm on a Map puts technical communication titbits onto an interactive map, together with the data and functionality provided by Google Maps. It’s a great way of seeing what we tech writers are up to, around the world. To find out more about the project, or to add something to the map, check out the project information page.

Tech Comm on a Map 2015

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 element imports the Google Maps JavaScript API library into the web page:

<script type="text/javascript"
  src="https://maps.googleapis.com/maps/api/js?key=YOUR-API-KEY&libraries=places">

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 <script> element:

&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 <div> element, with an ID, to define a place to put the map. In this case, I’ve called it “map-canvas”.

<div id="map-canvas">

Now the JavaScript can refer to that <div> 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 <div> 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:
<input id="place-search" type="text"
  placeholder="Search for a location">
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.

%d bloggers like this: