Category Archives: technical writing

Join us in a webinar on working with an engineering team

For a technical writer, working with an engineering team is fun and rewarding. Sometimes, however, it can be tricky to get the information you need from busy people who are focused on getting all the bits and bytes to play nicely together. How can a tech writer build a productive, mutually beneficial relationship with an engineering team?

Play with the teamI’m delighted to be working with the ASTC (Australian Society for Technical Communication) to present a webinar on working with an engineering team. Dave Gardiner is the organiser and Hamish Blunck is the webinar host.

Here’s a hint: I’ve found that engineers value the art of making words play nicely together too.

Webinar details

Date and time: Tuesday 1st November at 4pm, Australian Daylight Saving Time. (That’s 6pm in New Zealand, and 10:30am in India.)

Registration: See the ASTC webinar announcement. This webinar is free of charge.

I hope you can join us!

Musing about Write the Docs and ASTC and STC and more

So many options to choose from! As a technical writer in Australia, I can join a Write the Docs Australia meetup, the ASTC (Australian Society for Technical Communication), the US-based STC (Society for Technical Communication), and more. I’ve been putting some thought into the differences between Write the Docs on the one hand, and organisations such as ASTC and STC on the other. For me, they all have their place and membership of all of them is valuable.

I’m currently a member of Write the Docs Australia, and have also attended Write the Docs meetups in San Francisco, Silicon Valley and Portland. I’m a paying member of the ASTC and the STC, and support both by presenting at conferences or webinars whenever practical. I’ve also presented sessions at conferences organised by other bodies, such as TWIN and tekom.

Write the DocsFor me, Write the Docs differs from the more formal organisations in that it’s an informal community of people interested in technical documentation. The heart of the community is a series of meetups that happen in various parts of the world. There are also a few annual conferences. You don’t need to join an organisation – you just join a meetup, and then turn up.

Write the Docs is focused on documentation, rather than on technical writing. The community explicitly welcomes anyone with an interest in technical documentation. This includes technical writers, engineers, UX designers, support engineers, editors, and more.

The primary focus of Write the Docs meetups is API docs and developer tools, but other types of tech docs are becoming popular too. It’s up to us, the members of the community, to decide what we talk about.

So, for me, there’s a place for both types of organisation, even in a community of writers as small as Sydney or Melbourne. My aims are to share knowledge, learn, meet people, and spread good cheer.

And I haven’t even touched on the various social media groups and mailing lists on Slack, LinkedIn, LISTSERV, and so on.

What brought on these musings? The first Sydney Write the Docs meetup ever is at 6pm on Thursday 3rd November. Come along if you have an interest in, or a story about, tech docs – from any perspective.

Sign up here:

Have an idea for a talk for future meetups? Add questions or comments to this post, or add them as comments on the meetup page. Swapnil Ogale, the founder of Write the Docs Australia, would love to hear your ideas!

How to get started with Markdown and where to try it out

Technical writers have heard quite a bit recently about Markdown. Putting aside the question of whether Markdown is the right choice for technical documentation, it’s interesting as a tech writer to know more about the language itself. What is Markdown, where can we see it in action, and how can we try it out? Here are some pointers. If you have any other tips or stories about Markdown, I’d love to hear them!

Markdown is a markup language designed for quick and easy creation of simple documents. The syntax is pared down to the minimum, with the result that:

  • The syntax is easy to remember.
  • A Markdown document is easy to read, since much of the content is free of markup tags.

Along with the markup syntax, Markdown comes with a parser (a piece of software) that converts the markup to HTML, so you can display the document on a web page.

Other well-known markup languages are HTML, XML, reStructuredText, various forms of wiki markup, and many others.

Example of Markdown

Here’s a chunk of the above text in Markdown format, with an added level 2 heading, “What is Markdown?”

## What is Markdown?

[Markdown]( is a markup language
designed for quick and easy creation of simple documents. The syntax is pared
down to the minimum, with the result that:

* The syntax is easy to remember.
* A Markdown document is easy to read, since much of the content is free of
  markup tags.

Along with the markup syntax, Markdown comes with a parser (a piece of software)
that converts the markup to HTML, so you can display the document on a web

Equivalent in HTML

Here’s the same text in HTML:

<h2>What is Markdown?</h2>

<p><a href="">Markdown</a> is
  a markup language designed for quick and easy creation of simple documents.
  The syntax is pared down to the minimum, with the result that:</p>

  <li>The syntax is easy to remember.</li>
  <li>A Markdown document is easy to read, since much of the content is free of
    markup tags.</li>

<p>Along with the markup syntax, Markdown comes with a parser (a piece of
  software) that converts the markup to HTML, so you can display the
  document on a web page.</p>

Getting started with Markdown

When I first encountered Markdown, I already knew HTML and the wiki markup syntax used in Confluence. For me, the best approach to Markdown was:

  • First quickly scan the most basic syntax elements, to get an idea of the philosophy behind Markdown and to pick up the patterns. I’ve included some pointers below, to give you an idea of the patterns in the syntax. Note, though, that there are variations in Markdown syntax.
  • Then find a good cheatsheet and refer to it whenever you need to check up on something. Here’s a good cheatsheet.
  • If something doesn’t work, consult the full syntax guide.

Where can you try it out?

The best way to learn is to do.

  1. Grab my Markdown code from above, or write some of your own.
  2. Paste it into the text box at the top of Dingus.
  3. Click Convert.
  4. Scroll down the page to see first the HTML code and then the rendered version (HTML Preview) of your text.

Basic syntax

Here are those pointers I promised, to get you started.

Heading levels

# My level 1 heading
# Another level 1 heading
## My level 2 heading
### My level 3 heading
#### You get the drift


No markup, just an empty line before and after each paragraph.


Put the link text inside square brackets, followed by the URL in round brackets.

[Link text](

Another way of doing links is to define a variable for the URL somewhere on the page, and use that variable instead of the URL in the text. This is useful if you need to use the same URL in more than one place in the document, or if you want to keep the messy, long URL away from the text.

[Markdown] is a markup language,
blah blah blah - this is the rest of my page.


Bulleted list

* My list item
* Another list item
  * A list item embedded within the previous one
  * Another embedded item
* An item in the main list

There must be an empty line before and after each list, otherwise it gets mixed up with the preceding or following paragraph.

Numbered list

There are a few ways to do numbered lists. Here’s one:

1. My list item
1. Another list item
  * An embedded bulleted list item
  * Another embedded item
1. An item in the main list

You can mix and match bulleted and numbered lists, with varying degrees of success.🙂

More markup

There’s plenty more you can do with Markdown, and there are a couple of syntax varieties to trap the unwary. For example, GitHub has a special flavour of Markdown.

Recent articles about Markdown

There’s been a fair bit of discussion about the pros and cons of Markdown recently. Here are a few of them:

My opinion

In my day job, I write docs in both HTML and Markdown. I prefer HTML for comprehensive technical documentation. Markdown is good for very simple documents, but the syntax becomes clumsy for more complex things like tables, anchors, and even images. On the other hand, there are excellent benefits to using Markdown for quick collaboration on a document.

As is so often true, we need to choose the best tool for each use case. It’s a good idea to get to know Markdown, so that you can form an opinion and be able to use it when you need it.

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:

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

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.
 // 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="' +
     '?' + $.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 +
  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

%d bloggers like this: