Author Archives: Sarah Maddox
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 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:
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.
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.
Would you say “two types of widget” or “two types of widgets”? In other words, should we use singular or plural after the phrase “types of”?
This is a real use case. In a code review this week, someone corrected my use of “types of widget”. People have varied and vociferous opinions. It’s intensely interesting, especially to technical writers.
Since I was a babe in arms, I’ve always used the singular:
“There are so many kinds of chocolate cookie! Which one shall I try next?”
“What are your favourite types of dog?”
To me this sequence just looks odd:
Pick one type of car.
Pick two types of cars.
Surely, if we can grant the English language a modicum of mathematical elegance this should be correct:
Pick one type of car.
Pick two types of car.
So, why does the singular sound better to me? I think it’s because, when used after “types of”, the noun is acting as a concept representing a class of things, rather than a specific instance of the thing.
What do you think? Bring on the debate!
A kookaburra near my house:
The Australia chapter of the Society for Technical Communication has published an interview with me! It’s about building your personal brand, technical writing, and whether or not you’re emergent. Thanks very much to Tim Hildred for inviting me to be interviewed. It’s an honour. And thanks to Tim also for compiling such a great list of questions.
The pages were previously housed on the wiki associated with my book, Confluence, Tech Comm, Chocolate. That wiki is now shut down, but the tips live on!
These are the tips currently available:
- Bypassing the Confluence rich text editor interface
- Converting Confluence rich text editor content to wiki markup
- Converting Confluence storage format XML to wiki markup
- Editing Confluence pages in an external validating XML editor
- Validating Confluence XML storage format
- Showing tag names and some attributes in the Confluence rich text editor
- Promoting heading levels
- Searching Confluence storage format XML for content or markup
- Finding duplicate page names in Confluence
- Adding custom toolbar buttons to the Confluence rich text editor with Greasemonkey
Many thanks to Martin Cleaver at Blended Perspectives, for hosting this treasure trove of tips. And many thanks also to Graham Hannington, for all the work and insight he’s put into investigating and documenting the tips.
Looking for a Confluence wiki to play with while reading the book?
If you’re reading, Confluence, Tech Comm, Chocolate, you may want a wiki to try out the techniques described in the book. For the first 18 months after publication, a Confluence, Tech Comm, Chocolate wiki site was available for readers to experiment with. That site is no longer available. If you like, you can get a free evaluation licence from Atlassian, to experiment with Confluence.
Flowers from a recent walk in the Australian bush. Early spring.