Author Archives: Sarah Maddox

Practical HTML5 and CSS3 for real writers at ASTC (NSW) 2014

I’m attending the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. These are my session notes from the conference. All credit goes to the presenter, and any mistakes are mine. I’m sharing these notes on my blog, as they may be useful to other technical communicators. Also, I’d like to let others know of the skills and knowledge so generously shared by the presenter.

Dave Gash presented a session on “Practical HTML5 & CSS3 for real writers”. He promised us lots of code, “but nothing you can’t handle”. He also let us know that 11% of Americans think HTML is an STD. :)


Dave walked us through the current state of HTML, and HTML5 in particular. HTML5 isn’t a single thing. It’s a set of related things, some of which are supported now and some of which will be supported in future. So, when assessing whether a particular browser supports HTML5, you should look on a feature-by-feature basis.

Many of the HTML5 features are not particularly applicable to technical writing: Audio and video, canvas, geolocation, web workers and web sockets, and more.

For us as technical writers, focusing on content, the semantic structural elements are particularly interesting, such as <article>, <aside>, <nav>, and so on, that let us add meaningful HTML tags to our content. In HTML4, there were very few semantic tags. We end up using a large number of DIV tags, in series and nested. It’s very hard to discover the meaning in them. You can’t visualise how they’re used. HTML5 goes towards solving this problem.

To decide on the new tags, the W3C sent out bots that mined existing pages on the Web, analysed all the <div> elements that people are using, and created the new tags based on the results.

Note that the HTML5 tags don’t actually do anything. They don’t have any styles attached. You need to add the styling yourself. Elements that describe their content but don’t add style are the essence of structured authoring.


CSS3 also has a lot of stuff that’s not particularly useful to technical writers, as well as features that are.

Live demo

Dave walked us through a live demo, changing an existing web page from HTML4 to HTML5 and giving it structure and style. He showed us how to simplify the <html> and <head> elements, and walked us through the conversion of multiple <div> tags to the new semantic HTML5 elements. The resulting code was much easier to understand. Nesting of elements allows for a lot of flexibility.

The CSS on the sample page was fairly non-specific. It had mostly independent classes, which can apply to any element, and there was no obvious relationship between the content and the structure. The CSS class names used mixed case, which is a disaster waiting to happen. Dave changed this so the code was all lower case, and added dependent classes and descendent (contextual) selectors. These two techniques are useful to restrict the style to elements that are within another element, and thus reduce the chance of mistakenly applying styles to the wrong parts of the page.

Dave also showed us the CSS features that allow you to add rounded corners, shadows, drop caps, and link nudging (moving a link slightly on hover) via CSS3 transitions. First, you define a CSS transition on a specific link. Then use a hover pseudo-class to cause the transition to happen when the cursor hovers over the link.


I love Dave’s style. He had us roaring with laughter, which is quite a feat given the technical nature of the content. Thanks Dave!

Influencing without ‘real’ authority at ASTC (NSW) 2014

I’m attending the annual conference of the Australian Society for Technical Communication (NSW), ASTC (NSW) 2014. These are my session notes from the conference. All credit goes to the presenter, and any mistakes are mine. I’m sharing these notes on my blog, as they may be useful to other technical communicators. Also, I’d like to let others know of the skills and knowledge so generously shared by the presenter.

The conference keynote was presented by Haydn Thomas. He shared tips and techniques for influencing people of all sorts. When you’re providing content that transforms something complex into something simple, you’re using skills that are applicable to more areas than technical writing.

Haydn asked us to come up with the two major challenges that you face when you’re trying to influence a positive outcome. My neighbour and I came up with these two points:

  • Overcoming prejudices
  • Overcoming already ingrained ideas and assumptions

Haydn discussed the second point, saying that to resolve this, we need to influence the other person towards a positive outcome. Another person in the audience mentioned that we also need to be able to overcome our own assumptions. To do that, says Haydn, we need to constantly seek feedback.

Next, Haydn told us we need context. He illustrated this by asking us all to get up and go out through the door. Nobody moved. Instead, we asked, “Why?” We needed context. If we were told there was a fire outside, we’d have followed him out of the door.

Haydn’s aim was to teach us:

  • Adjust personal styles
  • Maximise leadership impact
  • Motivate others to act quickly


Haydn’s definition:

Influence is the ability to get things done through others because they want to do it.

We looked at the circles of influence and concern by Stephen Covey, to which Haydn adds the circle of control.

He talked about FEAR (Future Events Appearing Real) and how we can go out and find facts to counteract the fear. Document the objects and causes of the fear.

Another tip is to become aware of body language, as a means of communication.

An acronym used in change management


  • Awareness of the change that’s being requested
  • Desire, which leads to commitment
  • Knowledge – give people the facts they need to take action
  • Ability – turn the knowledge into ability
  • Reinforcement – reinforce the awareness, desire, knowledge and ability

The biggest cause of failing to influence people is missing out on the first two steps.

5 steps to influencing success

  1. Tell people what the impact of the change will be.
  2. Help them to understand the challenges. Work out the barriers.
  3. Share a solution. Find ideas.
  4. Remind people of the benefits.
  5. Get their agreement.

Types of power

Haydn talked about the types of power people have, ranging from the influence bestowed by a person’s position in an organisation or in society, through the influence held by experts, the influence you can gain by association with influential people, influencing people by giving them rewards, and other types of power. An interesting one was “informational”. Consider whether we gain more influence by withholding information or by sharing it.

The point is to decide what type of power we ourselves rely on most, and what type is used most by the people we’re interacting with. When you understand this, you can prepare and be proactive when wanting to influence people towards a successful outcome.

Techniques for influencing people

There are two tactical types of influencing:

  • the pull technique: convincing others to come with you.
  • the push technique: using persuasion or rewards and punishment to push people towards your goal.

When using the pull technique, share a common vision. Get people involved via participation and trust. The push style uses rewards or punishment to get people to do something, or simply just tell them assertively to do it.

Tactics – the ways to take action

When using the pull technique, get people excited, and get a group of people to come along with you. Try disclosing something about yourself, by sharing a story. Make sure you recognise people by giving them personal thanks. Adding emotional impact to an event ensures that people remember it. Test the potential solutions, and share the results. For example, ensure that our content can be seen in many different formats. Or test to find out whether visual or textual content works best in a particular situation. Value failure as a way of trying different solutions.

When using the push technique, you’re prescribing the goals and expectations. This works with some people, and not with others. Try using milestones, measurement and repeated evaluations as a way of getting people to do things. Or provide incentives and pressures. When using assertive persuasion, one technique is to offer just a couple of options, which encourages people to commit to one of them. Or you can lead people by listing the pros and cons. Get people to make the decision that they want to do something.

Resolving a difficult situation

Haydn finished by sharing a way of analysing a difficult situation that you may be in with a particular person. The techniques show you how to decide if the situation is a “state” or a “trait”, and the ways to handle each type.


The presentation handouts are very useful, both in their content and also in that they provide a kind of cheat sheet that you can use next time you need to influence another person towards a positive outcome.

Haydn’s presentation was very interactive and lively. He told some great, funny, engaging stories to illustrate the points he was making. We were all totally involved in the session. Thanks Haydn for a great kickoff to the conference.

Out of print: “Confluence, Tech Comm Chocolate”

A few months ago, I asked my publisher to take my Confluence wiki book out of print. The book is titled “Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication”. It takes a while for the going-out-of-print process to ripple across all the sources of the book, but by now it seems to have taken effect in most sellers.

solong_300pxWhy did we decide to take the book out of print? I’m concerned that it no longer gives the best advice on how to use Confluence for technical documentation. The book appeared early in 2012, and applies to Confluence versions 3.5 to 4.1. While much of the content is still applicable, particularly in broad outline, it’s not up to date with the latest Confluence – now at version 5.6 and still moving fast. I thought about producing an updated edition of the book. But because I don’t use Confluence at the moment, I can’t craft creative solutions for using the wiki for technical documentation.

Here are some sources of information, for people who’re looking for advice on using Confluence for technical communication:

  • If you have a specific question, try posting it on Atlassian Answers, a community forum where plenty of knowledgeable folks hang out.
  • Some of the Atlassian Experts specialise in using Confluence for technical documentation. The Experts are partner companies who offer services and consultation on the Atlassian products. The company I’ve worked with most closely on the documentation side, is K15t Software. I heartily recommend them for advice and for the add-ons they produce. For example, Scroll Versions adds sophisticated version control to a wiki-based documentation set.
  • AppFusions is another excellent company that provides Confluence add-ons of interest to technical communicators. For example, if you need to supply internationalised versions of your documentation, take a look at the AppFusions Translations Hub which integrates Confluence with the Lingotek TMS platform.

A big and affectionate thank you to Richard Hamilton at XML Press, the publisher of the book. It’s been a privilege working with him, and a pleasure getting to know him in person.

For more details about the book that was, see the page about my books. If you have any questions, please do add a comment to this post and I’ll answer to the best of my knowledge or point you to another source of information.

Want a REST API to play with?

Are you just starting out with REST APIs, or curious what they look like, and want one that’s easy to play with? Have a go at this tutorial I’ve just written for the Google Maps Engine API: Putting your data on a map.

A few things make it easy to play with the API via the tutorial:

  • You can get started immediately. All you need are a project on the Google APIs Console and a Google Maps Engine account, both of which are freely available. The instructions are in the tutorial.
  • The API accepts requests via an online interface called the Google APIs Explorer. So, instead of having to send HTTP requests and parse responses via the command line or within a program, you can just use an online form. The APIs Explorer prompts you for the fields and parameters that are required for each API request. I’ve integrated the APIs Explorer into the tutorial, so each step of the tutorial offers a link to the appropriate form in the APIs Explorer.
  • If you use the APIs Explorer, you can skip the bit about OAuth and client IDs. Yaayyy for a touch of simplicity when first getting to know an API!
  • The tutorial includes the full HTTP URL and request body for each API request. For those into Java, there are Java code snippets and a downloadable sample app.
  • After performing each step of the tutorial, you get visual confirmation of results. So, you’ll follow instructions to send a request via the API, then you’ll look at your account in Google Maps Engine online to see what’s changed.

More about Google Maps Engine, its web interface, and the API

Google Maps Engine provides a means to store geographic data in the Cloud, and to superimpose that data on top of the Google base map. Geographic data can be vector or raster. In the tutorial, you’ll use vector data consisting of a set of geographic points (latitudes and longitudes) with the associated information that you want to represent on a map (in this case, population growth statistics).

Google Maps Engine offers a web UI (user interface) where you can upload data and customise your map. It also offers an API (application programming interface), so that you can upload and manipulate your data programmatically. This particular API is a REST API, which means that it accepts requests and sends responses via HTTP. The requests and responses use JSON format to represent and transfer data.

When following the steps in the tutorial, you’ll use the API to do something, such as upload a set of vector data, and then you’ll look at the UI to see the results.

What you’ll have achieved by the end of the tutorial

When you’ve finished the tutorial, you’ll have your very own interactive map in Google Maps Engine, looking like the screenshot below. The circles show population growth (blue circles) or decline (red circles) in countries around the world. The size of the circle represents the size of the change:

Screenshot of map

Let me know if you try it

I’d love to know how you get on with the tutorial, and what you think of the API. Here’s the link again: Tutorial 1: Putting your Data on a Map.

How to track textual input with Google Analytics

This week an analytics ninja showed me how to use Google Analytics to track the values entered into a text field. It comes down to sending a dummy page name to Google Analytics, containing the value entered into the field. Google Analytics faithfully records a “page view” for that value, which you can then see in the analytics reports in the same way that you can see any other page view. Magic.

For example, let’s say you have a search box on a documentation page, allowing readers to search a subset of the documentation.  It would be nice to track the most popular search terms entered into that field, as an indication of what most readers are interested in. If people are searching for something that is already documented, you might consider restructuring the documentation to give more prominence to that topic. And how about the terms that people enter into the search box without finding a match? The unmatched terms might indicate a gap in the documentation, or even give a clue to functionality that would be a popular addition to the product itself.

It turns out that you can track input values via Google Analytics. The trick is to make a special call to Google Analytics, triggered when the input field loses focus (onblur).

<input onblur="ga('send', 'pageview', 'my-page-name?myParam=' + this.value);" />

The above ga call sends a customised page view to Google Analytics, passing a made-up page name that you can track separately from the page on which the input field occurs. The made-up page name is a concatenation of a string ('my-page-name?myParam=') plus the value typed into the input field (this.value).

The string my-page-name can contain any value you like. It’s handy to use the title of the page on which the input box occurs, because then you can see all the page views in the same area of Google Analytics.

Similarly, the part that contains the input text can have any structure you like. For example, if the page is called “Overview” and the input field is a search box, the Google Analytics call could look like this:

<input onblur="ga('send', 'pageview', 'overview?searchText=' + this.value);" />

This blog post assumes you have already set up Google Analytics for your site. See the Google Analytics setup guide. The Google Analytics documentation on page tracking describes the syntax of the above “ga” call, part of “analytics.js”.


Get every new post delivered to your Inbox.

Join 1,495 other followers

%d bloggers like this: