Blog Archives

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.

Tech Comm On A Map

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.

Tech Comm on a Map for AndroidOne 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.)

Tech Comm On A Map

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 Maphttps://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-map-screenshot_2016-08-22Tech 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.

Get it on Google Play

New Android app for the technical writing community

I’m super excited. I’ve just launched my first app on the Google Play Store: Tech Comm on a Map. It’s for technical communicators, to help us see what’s happening in the tech comm world. 

Tech Comm on a Map - Android appSee what’s happening in tech comm around you. If you know of something that’s missing from the map, you can add it yourself using the “Add event” option: a conference, meetup, business, or other item of interest to technical communicators.

As well as the Android app, Tech Comm on a Map is available on the Web too. The two apps use the same data source. The Web-based version has been around a while. The Android app is new and shiny: I published it to the Google Play Store this weekend.

I’d love it if you’d try it out. It’s even better if you have some events or other items of interest to share with the tech writing community, by adding them to the map. All additions are moderated before they appear in the app.

 

Get it on Google Play

 

Contributors to the project

The Android app is an open source project on Github. To kick off the project, a group of us got together during a hackathon and built the basics of the app.

Disclaimer

Although I work at Google, this app is not a Google product.

%d bloggers like this: