Author Archives: Sarah Maddox

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](https://daringfireball.net/projects/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.

Equivalent in HTML

Here’s the same text in HTML:

<h2>What is Markdown?</h2>

<p><a href="https://daringfireball.net/projects/markdown/">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>

<ul>
  <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>
</ul>

<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

Paragraphs

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

Links

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

[Link text](https://my.site.net/path/)

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.

[Markdown]: https://daringfireball.net/projects/markdown/

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:

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

First Write the Docs in Australia

The first Write the Docs meetup in Australia is happening soon! I’ll be there, to lead a discussion around working with engineers. Huge thanks to Swapnil Ogale for organising this first meetup ever in Australia.

The session will be in Melbourne at 6pm on Friday, 9 September 2016. Can you come? For more session details and signup, see the Write the Docs Melbourne meetup.

About Write the Docs

Write the Docs (WtD) is an informal community of people interested in technical documentation: technical writers, engineers, UX designers, support engineers, editors, and more. 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 belong to any organisation. Just register for a meetup in your area of the world.

Topic for the Melbourne meetup: Working with Engineers

Swapnil Ogale is the organiser of the Melbourne WtD meetup. He’s invited me to lead the discussion at this first session. We’ll talk about working with engineers. I’ll start with a presentation (about 20 minutes):

How does a technical writer build a super-productive relationship with an engineering team? Sarah has some tips gleaned from working with engineering teams at Atlassian and Google. The tips range from co-location (a fancy word for sitting together) to capitalising on your core skills as technical writer (a sure-fire way of becoming a valued member of the team), and more.

Are engineers keen to update the documentation themselves, and what might prevent them from doing so? See what some engineers replied to these questions.

We’ll close with a group discussion where people can share their own ideas and experiences. If it’s easy, bring your laptop or mobile device along, so that you can contribute to a shared doc.

If you’re an engineer or have another role that touches on technical documentation, come and talk about working with technical writers!

 

Eliminating the zombie vulnerability – removing passive voice from the docs

If you can insert the words “by zombies” into a sentence, then that sentence very likely uses the passive voice. A colleague recently reminded me of this tip. It made me laugh, and so I thought it’s worth blogging about. If only to share the chuckle.

Here are some examples of zombie-infested sentences, and their equivalents using active voice.

Example 1

Geographic requests are indicated by zombies through use of the coordinates parameter, indicating the specific locations passed by zombies as latitude/longitude values.

Converting passive voice to active:

You can use the coordinates parameter to indicate geographic requests, passing the specific locations as latitude/longitude values.

For an even more concise effect, use the imperative:

Use the coordinates parameter to indicate geographic requests, passing the specific locations as latitude/longitude values.

Example 2

Latitude and longitude coordinate strings are defined by zombies as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.

Converting passive to active imperative:

Define latitude and longitude coordinates as numerals within a comma-separated text string. For example, “40.714,-73.998” is a valid value.

Why eliminate the zombie vulnerability?

Active voice is more concise than passive voice. It’s usually easier to understand.

To me, the most important point is that active voice makes it clear who’s responsible for what. Putting zombies aside, if you use the passive voice your readers may think that the nebulous “system” may do the thing you’re talking about.

Who does what, in this example?

The API can return results restricted to a specific type. The restriction is specified using the types filter.

Answer: The developer has to specify the types in the types filter. I don’t think that’s clear, though, when reading the text. Often the context makes it clear, but not always. Zombies lurk in the shadows, ready to grab the unsuspecting reader.

The distinction between active voice and imperative mood

In the above examples I’ve pointed out the difference between active voice and imperative mood. In technical writing, both are good. The imperative mood is particularly concise and clear, but in some cases it can come across as too abrupt.

Should we ever invite zombies in?

I think there are times when passive voice is OK, or even a good thing. Sometimes a sentence sounds artificial if you attempt to inject a subject. Sometimes the passive wording is a well known phrase that readers will accept and understand more easily than the equivalent active phrasing. For example, what do you think of this wording?

These community-supported client libraries are open-sourced under the Apache 2.0 License and are available for download and contributions on GitHub. The libraries are not covered by the standard support agreement.

%d bloggers like this: