2018 conferences now open on Tech Comm on a Map

The Tech Comm on a Map application now caters for 2018 conferences. This week I updated both the web app and the Android app to accept data for 2018. I also archived the 2016 conferences.

Tech Comm on a Map is an interactive map showing items of interest to technical communicators around the world: conferences, groups, businesses, societies, courses, and other things we find interesting. Tech Comm on a Map is available as a web app (see the previous link) and an Android app.

Highlights of the latest update:

• I’ve added a  option, which you can click to add items to the map (new in the web app only; the Android app already has an Add event option in the menu).
• I’ve added a data type for 2018 conferences, and archived the 2016 conferences (web and Android).

Each coloured dot on the map represents a conference, business, society, group, course, or something else. Click a dot to see what it’s about.

Adding 2018 conferences and more

The map is now able to accept 2018 conferences, but there’s not much data on the map for 2018 yet. At this point I’ve added just two 2018 conferences. I’ll add more over the next few weeks.

If you have time, please do add items to the map: 2018 conferences, groups, societies, educational courses, and more. It’s also fun to add tidbits that you think are of interest to tech writers and have a geographical relevance. For example, the Other item type includes the birthplace of Ada Lovelace. Try de-selecting all event types except Other, and see what’s there now.

To add an item:

• Click the new ⊕ icon  on the web app.
• Or select the Add event option in the menu in the Android app.

If you’d like to know more about the apps, how they work, and where the data comes from, take a look at the page about Tech Comm on a Map.

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.

What do you want to know about Tech Comm on a Map?

I’m putting together a presentation about Tech Comm on a Map, the app that shows technical communication events and groups around the world. What would you like to know about the web app and the Android app for Tech Comm on a Map?

It’s a little scary for a tech writer to create and publish an app. Actually, it’s a little scary for anyone. Are you curious about any particular aspects of why I did it, what the results are, or anything else? If I can, I’ll weave the answers into the presentation.

I’ll be speaking about Tech Comm on a Map at STC Summit 2017 in May, and possibly at other events after that. At the moment, I’m writing the presentation based on my early proposal and outline. I’m having fun! But before I get too invested in what I think is fun, I’d love to hear what other people think too.

The theme for STC Summit 2017 is “Gain the Edge to Get Results“.

Here’s the blurb and outline from the proposal I sent to the STC Summit committee.

Blurb

As an API technical writer, it’s hard to put yourself in the shoes of your readers. They’re application developers. They’d rather read code than prose.

One way of grokking this audience is to develop an app yourself.

This presentation tells the story of a tech writer, a map, and an app. The app is Tech Comm on a Map, an interactive web-based map that shows events of interest to technical communicators. You’ll hear why Sarah decided to create an app and how she went about it. 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.

Tech Comm on a Map is an app for technical communicators, and technical communicators contribute to the data. Sarah will describe the process of crowd-sourcing the data and open-sourcing the app: what went well, what went slowly, what’s still going.

Writing an app has helped Sarah understand her audience (software engineers), her subject matter (APIs), and her profession (technical communication). Come and see how.

Outline

It’s hard to create an app. It’s even harder to get the app published and make it available to other people. That’s true whether you’re a developer or a technical writer. You need to put yourself on the edge and take the jump. You need courage, strength of conviction, and knowledge. Above all, you need documentation and examples. They give you the edge.

By taking the jump into app development, Sarah has gained first-hand knowledge of what developers go through. She applies this knowledge to the documentation she writes. It’s also a lot of fun!

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, from a developer’s as well as a user’s point of view. Tech Comm on a Map is available as a native Android app as well as a webapp.
• The information sources that Sarah used when developing the app.

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

• Sarah’s engineering colleagues helped her 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.

See Tech Comm on a Map in action at https://sarahmaddox.github.io/techcomm-map.

What are you curious about?

Does the above description raise any specific questions in your mind? Is there something you’re very keen to find out? Let me know, and I’ll include it in the presentation if I can.

New in Tech Comm on a Map: Share an event easily from the map

I’ve spent the last couple of days immersed in JavaScript and jQuery, and emerged with a new feature on Tech Comm on a Map: You can now grab a link to the location of an event, and use that link to open the map directly at that location. Handy for sharing event information!

When you look at the information for an event on the map, you can now see a new line at the bottom of the popup, “Link to location on map”.

(Click the image to see a bigger version.)

Copying the link gives you something like this:

https://sarahmaddox.github.io/techcomm-map/?lat=-37.822547&lng=144.96512&zoom=14

You can use the link to open Tech Comm on a Map at a given location. This makes it easier to share information from the map with your colleagues and friends, because you can send them to exactly the right spot on the map.

Go ahead and try it!

To see it in action:

1. Open Tech Comm on a Map: https://sarahmaddox.github.io/techcomm-map
2. Click on any of the events, to see the popup containing the event information. (Make sure you click, rather than just hovering. The links don’t appear when you’re just hovering.)
3. Right-click on “Link to location on map” and copy the link, or just click to open it immediately.
4. Share the URL with someone. They’ll see the same location on the map.

How it’s done

Copying the link gives you a URL that looks like this:

https://sarahmaddox.github.io/techcomm-map/?lat=-37.822547&lng=144.96512&zoom=14

The URL includes the Tech Comm on a Map base URL plus following parameters:

• lat=VALUE – A latitude that positions the centre of the map along the north-south axis.
• lng=VALUE – A longitude that positions the centre of the map along the east-west axis.
• zoom=VALUE – A zoom factor that determines the level of detail shown on the map.

You can see all the code on GitHub. To add the link sharing feature, I had to do two things:

• Add a link in the information for each event, pointing to the event’s location.
• Make it possible for the map to open at a given location.

Adding a link that contains the event’s location

The data for Tech Comm on a Map already contains the location for each event, because that’s needed to show the event on the map. All I had to do was grab the latitude and longitude from the data, use it to construct a URL, and then add some text to the event information popup, hyperlinked to that URL.

Sounds simple, huh? It turned out to be a little more complex than I expected. I’m using jQuery as a neat, safe way of constructing the information to display for each event. The first step is to create a paragraph with a class name that I can refer to later. The following jQuery appends a paragraph <p> to my existing content, and gives the paragraph a class of "link-map":

var content = $('<div id="infowindow" class="infowindow">');
// Create the rest of the content here.
content.append($('<p class="link-map">').text('Link to location on map'));

The next thing is to add the HTML for the link. After a bit of reading, I decided the best way is to use jQuery’s wrap function. At first, I added the wrap immediately after appending my paragraph to the content. But that didn’t work – the link didn’t appear. Some experimentation taught me that it works if I do the wrapping after I’ve set the content on the map’s InfoWindow object:

 // Add the content to the info window, and thus to the DOM.
 infoWindow.setContent(content.html());
 // Now that the DOM is ready, we can wrap an HTML link around the divs
 // that we want linked.
 // For the map link, get the latitude and longitude (geometry) object from
 // the event data then add a default zoom.
 var position = feature.getGeometry().get().toJSON();
 $.extend(position, {zoom: AUTO_ZOOM});
 // Put it all together into an HTML link.
 $('.link-map').wrap('<a href="https://sarahmaddox.github.io/techcomm-map/' +
     '?' + $.param(position) + '"></a>');

The latitude and longitude are held as a “geometry” object in the event data. For the zoom factor, I use a default value of 14, which the map also uses to zoom in when you click on an event icon.

Opening the map at a given location

Up to now, the map opened at a default location. To allow sharing of the event location, I added code that reads the URL parameters and uses the information there, if present, to set the initial latitude, longitude and zoom factor of the map.

Once again, some reading yielded a nice jQuery solution which I found in this Stack Overflow post. The following function returns the value of a URL parameter with a given name:

$.urlParam = function(name) {
  var results = new RegExp('[\?&]' + name +
      '=([^&#]*)').exec(window.location.href);
  if (results == null) {
    return null;
  }
  else {
    return decodeURI(results[1]) || 0;
  }
}

To use it, I call the $.urlParam() function when setting the centre and zoom on the map:

map = new google.maps.Map(document.getElementById("map-canvas"), {
  // Examine the URL parameters for a specified location and zoom.
  // If not present or if invalid, use defaults.
  center: validateLatLng($.urlParam('lat'), $.urlParam('lng')), 
  zoom: validateZoom($.urlParam('zoom')),
});

There’s also a bit of validation, which you can see in the code on GitHub.

What’s next?

What about the Android app, you may ask, will we be able to share an event’s location more easily there too? Stay tuned, that’s my next task! I’m keeping track of feature requests and bug reports on the GitHub issue tracker. See the issues for the web app and for the Android app. They’re both open source, and you’re welcome to get involved.

Add 2016/17 events to the map

Tech Comm on a Map is ready for 2017! I’ve added a category for “Conferences 2017” and styled it a cool grey. (Grey is THE colour for 2017, right?)  The map already has a few events scheduled in 2017. If you know of any more, it’d be great if you’d add them.

Tech Comm on a Map (available on the web and as an Android app) puts technical communication titbits onto an interactive map.

Add events, groups, societies, businesses and more

The data on the map is crowd sourced. If you know of an event, a business, or something else related to tech comm, please add it. You can use this online form, or you can use the Android app (see below).

See the map on the web

See Tech Comm on a Map in action in your browser. Plot tech comm events and organisations around the world. You can even embed the map into your own web page. See the details.

Grab the Android app

Tech Comm on a Map (Android) is available as an Android app.