Refactoring overlays in the Google Maps JavaScript API documentation

One of my first big projects as a Google technical writer was to refactor the “overlays” part of the Google Maps JavaScript API documentation. In this post, I’d like to share the aims and results of the refactoring with you.

Did you know you can draw shapes on a Google map, just by creating an HTML page and including a bit of JavaScript? Or that you can add your own pictures and tiles to the map? I didn’t, until recently. The documentation explains the concepts upon which the API is based, and tells you how to use the classes, methods and events to draw objects and shapes on a map. The general term for this sort of shape or object is an “overlay”.

It had been a while since the last major overhaul of the overlays documentation. My team wanted to improve its usefulness to developers, by making it clearer and more readable.

Before

Before my updates, the overlays documentation was all on one very long page. The page told you how to add polygons, polylines, rectangles, circles, markers, info windows, and various custom shapes to your map.

Here’s a “before” image. On the left is the list of pages that make up the documentation, with the selected page (“Overlays”) highlighted in red. On the right is the table of contents built from the headings on the page:

After

Here’s the “after” image:

So, now we have a short introductory page that explains the various types of overlays you can draw. Each type of overlay has a page dedicated to it.

There are three parts to the documentation:

• The guides to each type of overlay, starting on this page: Drawing on the Map.
• The interactive code samples, starting at Simple Markers and going up to Dashed Lines. I’m rather fond of Rectangle Events. You can move and resize the rectangle. An event listener spots that you’ve done something, and helpfully pops up an info window!
• The reference guide, which I did not change.

Why refactor?

In this refactoring exercise, my aims were:

• Add more code samples, to help developers grok the API quickly.
• Employ content reuse for the code samples, so that we’re using the same piece of code embedded in the text and in the interactive samples, rather than copying and pasting code.
• Improve readability, by making it easier for people to grasp just one part of the API at a time, and to see the scope of the material they need to follow in order to draw a particular shape.
• Change the top-level page title from “overlays” to “drawing on the map”. We had a lengthy and interesting debate about what to call this page. “Overlays” was too obscure. (How many people would search for “overlays”?) We thought of “data visualisation”, but that seemed too grandiose. In the end, “drawing on the map” won the day. For now, anyway.
• Help people find the section they need, by exposing the different overlay types on individual pages and making them visible in the left-hand navigation panel.
• Improve SEO (search engine optimisation) by providing a meaningful title for each type of overlay.
• Experiment with short-form verbs in headings. Instead of gerunds in headings, we’re using just the verb stems. So, instead of “adding a widget” we’re saying “add a widget”. This looks like an imperative, but in this case it’s not meant as such. It’s just a short form of the verb, and more likely to match what people will search for on the page.

Tackling a refactoring exercise like this is a very good way for a new team member like me to get to know the documentation and the APIs. 🙂