Blog Archives

Documenting the tools you use – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Swapnil Ogale presented a session titled How do you document the tools you use? His presentation was about being a technical writer on a product that you also use.

A quick look at some tools with good docs

These are the tools Swapnil uses regularly, for both business and personal use:

  • Snagit
  • Meetup
  • Slack
  • Confluence
  • Pocketbook (an expense budgeting tool)

All the above products provide a decent set of documentation and tutorials. Swapnil gave us a quick overview of the help/documentation systems provided by each tool. In some cases, he said, the documentation was easier to use than the actual product.

Introducing rounded (a software application)

Swapnil also uses a software application called rounded, and has contributed to the documentation for the application. Rounded is an accounting tool designed and built by Australian freelancers and sole traders.

When Swapnil started using rounded, he found that there was no documentation, and some of the UI was a little confusing. So he got in touch with the company and offered his help. They hadn’t considered the need for documentation up to that point.

Experiencing rounded as a customer

Swapnil talked about his initial experiences as a product user:

  • He didn’t know what to expect from the product. Up to that point, he’d been using a collection of spreadsheets for accounting. He was looking for something to make things easier.
  • It wasn’t clear why he should use the product.
  • He needed an overview of features that would help make his freelancing life easier. Timetracking was the number one feature he was looking for. Another was reporting.
  • He wanted to know if the product supported automation, such as breaking his work into smaller elements of time.

Luckily, rounded did cover all his needs. He had some questions though, and he thought it was likely other users had the same questions. Hence his offer to create the docs.

Documenting rounded

The client brief that rounded gave to Swapnil was:

Create content that describes how to use the product, is simple to read and understand, and makes it easy for new users to learn the product.

They needed something that was a simple as spoken language, rather than technical.

Swapnil created an information plan (just one or two pages describing expectations and deliverables). He created a design prototype in the form of a wireframe, using a tool called Pencil.

The early workflow: To draft the documentation, he used Gitbook. When the client was satisfied with the drafted content, they copied it and pasted it into WordPress, and used WordPress as their publishing platform.

The current workflow: Swapnil uses Google Docs to draft content, which makes commenting and reviews easy. Then the client copies the content and publishes it to Intercom.

The ongoing story of the docs

When Swapnil first created the docs, he documented his own workflow and use case. Then he needed to think about how other customers were using the product and what their needs were. To find the answers, he looked at some customer feedback. Some of the feedback was useful, but some of it was way off topic. Next, he talked to the analytics team. They had useful data on the way recent changes in the UI had changed customers’ approach to the product.

The customer requested a change in voice and tone of the content. They wanted a more conversational language, and Swapnil did his best to satisfy that requirement.

Another request from rounded was to add the “so what” factor. The docs should help customers understand why they should do something. For example, why would you want to create an invoice. Look at real customer examples to provide relevant content. Swapnil recommends that you tell a story when creating the docs.

Thank you Swapnil for an interesting look at a tech writer’s experiences as both a customer and a documenter.

The wonder of walkthroughs – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Sonja McShane presented a session called The wonder of walkthroughs. This was her second talk at the conference. Nice work Sonja!

The problem that led Sonja to use walkthroughs was a very confusing experience that her company’s website presented to customers. Sonja demonstrated a tool called WalkMe. According to Walkme’s marketing content, the tool helps you to “foster optimal customer journeys, reduce needed support and ensure user adoption with intelligent guidance”. [Sarah’s note: It looks like a tool that helps you build a guided help experience on your application or website.] In Sonja’s session we saw a “quick tour”, a “help centre”, and a “show me how” walkthrough. In the “show me how”, for example, the user can click a button and follow the guided tour to complete fields on the form.

Using WalkMe, you can add tooltips, validate field values, and lead a user through a process. There are a number of other options too, including surveys, live chat, search, and more.

What about single sourcing? A walkthrough solution kind of does it for you. Because each piece of information is linked to the UI, this means that you don’t have to repeat the same information for each separate use case. The help content for the shared functionality uses the same tooltip or help item.

How do you choose which parts of the website need a walkthrough? Sonja’s team looks at user feedback, customer surveys, and other channels. WalkMe provides analytics and insights that help you see how your customers are using the site and the obstacles they encounter. You can use the output of the analytics to decide which walkthroughs to create next.

There are other tools available that offer similar functionality to that offered by WalkMe. [Sarah’s note: Try searching the web for “guided help tools” or “walkme alternatives”.]

Thank you Sonja for an introduction to a useful tool.

CSS Variables – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

He’s back! Dave Gash’s second session of the conference was CSS Variables: No, really! Dave said using CSS variables is easy. Let’s see whether he convinces me.

In the early history of CSS variables, there were some changes in implementation. The changes resulted in improvements, but not all browsers supported every version. Browser support for CSS variables has improved over the last year. It’s reached around 70-80% according to

Why use variables in CSS? The benefits are the same as in other types of coding:

  • Ease of maintenance
  • Simplicity
  • Consistency

Declaring a CSS variable is the same as declaring any CSS selector, except that you need to add a double dash in front of the variable name. Examples:

--bqindents: 40px;

--warningtextsize: 125%;

It’s good practice to declare all your variables at the top of your page, using a :root selector. The :root selector gives the variables global scope. Use it like this:

:root {

  --bqindents: 40px;

  --warningtextsize: 125%;


To use the variable later in the CSS, you use the var function to retrieve the value of the variable. Example:

p.warning {


  font-size: var(--warningtextsize);


Dave ran through a number of best practices for using variables, and pre-emptively answered some FAQs. Then he walked us through some examples of where variables are useful. You can find some demos of CSS variables on Dave’s website. Dave has also written an article about them on Medium.

Thanks Dave, that was informative and fun. And yes, it does look kinda easy, now that you’ve shown it to us. 🙂

Framework for evaluating communication – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Neil James presented a session titled Will it work? A new integrated framework for evaluating communication. Neil is the executive director of the Plain English Foundation.

The first question that Neil addressed was, “Why do people write ‘Manglish’, or mangled English?” This topic wasn’t a prepared part of his presentation. Instead, it was something the conference organiser asked Neil to consider, following on from a session yesterday. Here are some of the contributing factors that Neil mentioned:

  • At school, we imbibe the notion that complex writing is better writing. Waffle gets reasonable marks, provided it’s elegant waffle.
  • Early in our careers in the professional and technical workplace, mastering and using the technical jargon of our field gives us a stronger feeling of belonging.
  • When we learn the tech vocabulary of a particular industry, it’s difficult to adjust to communicating with a lay audience.
  • Institutional culture reinforces the language patterns. Large organisations move slowly. It’s hard to change their processes. When you do successfully introduce change, the organisation moves steadily along the new path.
  • Language is used as an expression of power. Sometimes, people deliberately use jargon to protect their financial interests or to manipulate public opinion. An example is from the airline industry, when people use the term “loss of separation” of two planes, which means the two planes collided.

Evaluating technical communication: Testing versus techniques

Neil talked about the various ways of evaluating technical documentation. There tend to be two groups of people: those who focus on user testing, and those who focus on techniques such as readability formulas.

Communication professionals tend to evaluate their work using a technique they learned near the beginning of their careers, and to use a fairly narrow range of techniques. Neil advocates making wider use of the spectrum of methods available.

Neil’s talk covered:

  • The evaluation methods available
  • Criteria for selecting the right method
  • Examples

The spectrum of evaluation methods

One of the key things that’s happening to our role is that we need to produce a wider variety of technical communication. Neil says we also need to consider a wider range of evaluation methods and tools.

The methods for evaluating tech communication tend to focus on the following three areas, which Neil talked through in detail:

  • Focus on text – tool based or expert review
  • Focus on users – preference testing or performance testing
  • Focus on outcomes – transactions (such as errors, phone calls, revenue) or attitudes and behaviours

Note that you can blend and scale these techniques to suit your environment and requirements. The various methods are not as difficult as we sometimes think they are, and learning about them adds to our professional expertise.

Criteria for selecting the right method

Many of the criteria are familiar to communication professionals. The value of the framework is that it brings these criteria together in a structured way.

Here’s a summary of the factors that affect your choice of method:

  • Requirements related to the reader:
    • Number of readers, literacy skills, knowledge of content.
    • Complexity of the content and of the task.
    • Urgency of the task.
  • Requirements of the business:
    • Timing (standard to disruptive).
    • Costs.
    • Risks.
  • Outcomes shared by both: Purpose and impact of the communication. Sometimes the purpose of the communication may be perceived differently by the organisation and the reader. Similarly for the impact.

Putting it all together

Neil showed us a tabular representation of the above items, which you can use to decide which types of evaluation to use. He then ran through some examples showing where and how he’d used the framework to decide which types of evaluation would be useful for some specific use cases.

The framework is still in its early days. Neil and his colleague, Susan Kleimann, are still testing the framework and getting feedback on it from customers. One point he emphasised is that the framework helps to secure budget for the evaluation part of a project. Once you put the framework in front of customers, they can see the need for the evaluation phase.

To get a more visual idea of the framework, take a look at an early version of the slides from a conference in Dublin in 2015. Neil confirmed that the information on those slides is essentially the same as presented today.

Thanks Neil for introducing a useful framework.

A tech writer, a map, and an app – ASTC 2017

I’m attending the Technical Communicators Conference 2017, which is the annual conference of the Australian Society for Technical Communication (ASTC). This post is about the session I presented at the conference.

I presented a session called A tech writer, a map, and an app. The session is about my experiences developing an app, why I tried my hand at app development, and what I learned from the experience. The app itself, Tech Comm on a Map, is an interactive map that shows events of interest to technical communicators. The app is available on the web and on Android.

The presentation included a technical overview of the app and what went into developing it:

  • The nuts and bolts of a web-based application like Tech Comm on a Map: where it’s hosted, where the data is stored, the JavaScript code and the APIs that create the map and the app’s functionality.
  • The difference between a web-based application and a mobile app. Tech Comm on a Map is available as a native Android app as well as a webapp.
  • Where the app’s data is stored, and how it’s crowd sourced.
  • What open sourcing means, and why you may want to open source your code.
  • The information sources that I used when developing the app.

I’ve learned much from the experience of developing an app, including:

  • Interactions with my engineering colleagues have increased mutual understanding and respect.
  • Fellow technical writers all over the world help compile the data. A project like this is a good way of connecting with your peers.
  • Developing an app has helped me better understand my audience of software engineers, by experiencing their needs and problems first hand.
  • The project has given me confidence in my own abilities in a highly technical field.

The slides for my presentation are available on SlideShare: A tech writer, a map, and an app. You can also read more about the app, Tech Comm on a Map.

%d bloggers like this: