Author Archives: Sarah Maddox

Con­tent strat­egy: getting it and testing it 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.

Carol Barnum‘s keynote presentation was titled “Con­tent Strat­egy: How to get it, how to test it?” Carol introduced content strategy, then shared some work she did with clients that focused on content, showing a success and a failure.

Content strategy

Carol started with the definition of content strategy (CS) from Wikipedia:

Content strategy refers to the planning, development, and management of content—written or in other media. The term is particularly common in web development since the late 1990s. It is recognized as a field in user experience design but also draws interest from adjacent communities such as content management, business analysis, and technical communication.

A definition from the Content Strategy Consortium:

CS is the practice of planning for the creation, delivery and governance of useful, usable content.

The two key points are planning and usability.

Carol gave us a short history of CS, and some reference material and the people involved, showing how new the field is. It’s a good time to get involved! Looking at the authors of the books, they’re mostly technical communicators. Yet somehow, we’re not deeply involved in the core discussions. It’s time for us to take the initiative here in Australia. Carol showed a map showing that the main interest was in the US, followed by Australia, then the UK, Canada and India.

What do content strategists do?

Audit the existing content, figuring out where it resides, when last updated/accessed, what is still relevant, and so on. This provides a high-level overview of the content.

Plan for the creation, publication and governance of useful, usable content. How you’re going to update, remove and create content.

Manage the content creation and revision.

Create content.

We may be currently engaged in the last activity. To move up the ladder, add the earlier steps to what you do. This will help to prove our worth and become more valuable to our organisation.

Ensuring your content is useful and usable

Be there to see where the users struggle. Especially when there’s no help or user assistance yet, this will help guide the content creation.

Top findings in usability testing: People can’t find what they’re looking for. They get stuck navigating around the site. They don’t understand the terminology, or there’s inconsistency in the use of words. The page design is confusing or not accessible. The design of the interface doesn’t match the users’ mental model. The users bring expectations based on previous experience, and a good user experience (UX) design will tie into these expectations.

What about the content specifically? Users need to be able to find the content. Next, they need to understand it and be motivated to take action. And they need to be able to complete the action satisfactorily. Were they happy or frustrated at the end of the process?

Carol talked through a list of techniques on making your content work for users.

Case study: Green Engage

Green Engage is a web app produced by Intercontinental Hotels Group for general managers of their hotels around the world. The app allows the managers to create plans and track progress of projects aiming to make the hotels green, that is, environmentally friendly.

The app is content based. Carol’s team did a round of usability testing with 14 users. Carol recommends a group size of 10-15 people (so, a small group) of people who are deeply engaged in the subject. The customer’s requirements were to test navigation and workflow, defects and system feedback issues, perceptions around content, and training requirements. Carol emphasised specifically the term “perceptions” in this list of requirements, which came from the customer. Carol thought there were problems with this list of requirements, but went with it.

The first round of testing showed that users liked the idea of the system, but found it hard to understand. There was no user assistance at this time. Of the 14 users, 4 people called for help – they called 11 times. In other words, they were good and stuck. The existing content was overwhelming and unhelpful.

Eight months later, round 2 of the usability testing happened after a complete redesign of the system. The system was redesigned, but the content was exactly the same. There were no technical communicators involved. The requirements for the testing were the same, but with a new goal: Measure the SUS (System Usability Scale) score improvements. Carol recommends this scale as an excellent measure. The average score is 68 – you can use this as a benchmark for measuring your own results. The next step is to measure your own benchmark, so that you can raise your own score over time.

The SUS score from round 1 was 54. This is bad, and not surprising. Round 2 had a SUS score of 73.

Five months later was round 3. There were only 4 users in this study, so we need to use caution when drawing conclusions. This study happened during a pre-launch of the system. Users loved the new system, in comparison with the old system. They found the homepage helpful and that the app supported their goals. The SUS score was 94! Don’t pay too much attention to that – it was only 4 users and they were comparing the new system to the bad old one.

Carol’s team suggested another round, using new users as well as existing ones, employ some tech writers to improve the content and add context sensitive help. so round 4 happened one year later, with 16 users including new and returning ones. The focus was on the content, with a goal to find out how well users understand and can act upon the content. The test gave users a specific set of tasks, based on their use of the content and a specific goal to achieve.

Feedback showed that users had a goal (get profit for their hotel) rather than wanting to read content. They wanted a solution, not an idea. On the negative side, users couldn’t find what they wanted. They were confused by the terminology, and there was a lot of content, but not useful and not well organised. The SUS score was 50. Carol says this was fantastic, because it shows they had work to do. It was the first time content creators were involved.

Case study: Footsmart

Footsmart is a website for people who have troubles with their feet. Carol did one usability study of a single template.The study compared the original content (A) with the new (B). Users would see one or the other, and did not know which they were seeing.  The goals were to verity that the new content (A) was effectively communicating with users, to understand how users responded to the content (e.g. it’s voice and tone) and to see if they acted upon it.

Carol showed us examples of A and B. The new content was better laid out, and included graphics.

All 6 participants liked the newer content better and found the thing they were looking for more easily (heel cushions). An interesting conclusion from the detailed results is that people asked for more content in the redesigned site (B). In other words, perhaps you should show them a little at first and give the option to find more content for those who want it.

How to start as a content strategist

Plan the content you control. Create an overview of the types of content on the user interface (UI) such as labels, buttons, help text, etc. Think about the tone and treatment of that UI content. Create personas of your users, and collaborate to develop those personas. Create a style guide based on your conclusions from the above steps. And become involved in usability testing yourself, or even run one yourself.


Thanks Carol for a very good introduction to content strategy. The case studies were fun and interesting, and a good illustration of how usability testing fits into an overall content strategy.

Repco and DITA 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.

Gareth Oakes walked us through a case study of an automotive content management system that he designed and implemented in collaboration with Repco. The content is stored and managed in DITA format, and published on a website.

Overview of the system: Autopedia

Repco supplies automotive parts in Australia and New Zealand, dealing with retailers as well as their workshop division. They were founded in Australia in 1922. The system is called Autopedia, a subscription product for mechanics and workshops. It provides automotive service and diagnostic information for the majority of vehicles on the road in Australia. For example, diagnostic codes, wiring diagrams, procedures for replacing timing belts, and so on.

Autopedia is a replacement for an “encyclopedia” in the form of a CD that was mailed out to the mechanics. The content was written by Repco technical writers. It was becoming more and more difficult to keep up with the number of vehicles, and variations of vehicle, on the road. It was expensive to maintain the content. And customers wanted online content, not CDs.

Designing a solution

Repco came up with a vision for a replacement system, and Gareth’s team worked with them on the technical solution.

A summary of what the solution comprised:

Content (Repco & third party) -> DITA -> DITA CCMS -> HTML -> Web server

(CCMS = Component Content Management System. The team uses the Arbortext Content Manager.)

The team wrote a multiple conversion pipeline, consisting of a set of Java tools, to convert the content into DITA format. A vehicle mapping table related the vehicle models in other countries to the Australian models. At first this required a lot of quality control, but now it’s up and running it doesn’t need so much attention.

Creating and storing the content

All content is stored as a simple DITA topic. The aim was to keep the system simple. Each topic is tagged to indicate which vehicle it applies to. Other semantics are added when required to support the needs of website display. This was done iteratively, as the need arose. For example, in a voltage table you may want certain values to stand out.

Repco content makes up only 1% of the content. Repco now authors all new content in DITA, using Arbortext Editor. Third-party content come from a vendor in the USA, in multiple formats: database, CSV, custom XML, images. The automatic process converts all this to DITA topics, grouping the topics by vehicle applicability. The system then does a diff process and sends only what’s changed to the web.

Delivering the content

All content is converted to HTML and sent to the web server (Umbraco). The vehicle mapping table is used to decide where the content belongs in the navigation structure. Images are hosted on a CDN (Content Delivery Network) hosted by Rackspace. Topics are marked as published or unpublished on the web service, so separating the publication process from the content storage and update process, and allowing the publishing process to respond quickly to customer feedback.

Project timeline

In all, the project took approximately 9 months. The team was reasonably small: approximately 9 people across the various teams at both GPSL (where Gareth works) and Repco.

(Members of the audience at Gareth’s session expressed surprise at and admiration for the short timeframe of this project.)

The initial design sessions with Repco took approximately a month. The other phases included planning sessions with the web team, development of the code and the vehicle mapping table (which took around 6 months), and migration of existing content to DITA. Then following integration of all the components, and testing. Documentation, training and knowledge transfer was important. Then the initial conversion and content upload took a while – more than 200GB. Then came the go live date, and ongoing support.

Results of the launch

The project launched late in 2012. The response from the market was very positive. They achieved their revenue goals and ROI well within the first year. Most existing customers migrated to the new system, and more than 1000 new customers signed up.

A few project notes

DITA was a good solution for this system, using basic topics and a very light layer of specialisation for vehicle tagging. The team may need to add more specialisation in future, based on customer demands for dynamic representations, such as decision tables. A next step may be a live link to parts, so that the parts are ready when you come in to work the next day. The single sourcing aspect is extremely useful. Store the content in one place and be able to output in many formats, such as PDF. The team found DITA easy to work with, as there are many tools available.

You need a level of skill with XML. DITA also very much steers you to author your content as topics, which may not suit every solution. You may also need new tools. And with a laugh, Gareth said that you risk turning into one of those DITA fans who runs around recommending DITA as a solution for everyone else. :)

The huge amount of content caused many delays, which were not entirely expected. The information structure required a number of design changes during development, due to the complexity of vehicle classification. The DITA CCMS required a lot of specific configuration and optimisation to ensure it was performing as required.


Thank you Gareth for an insight into a very interesting project and a cool system.

STE: quirks and limitations 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.

Lyneve Rappell spoke about the quirks and limitations of STE (Simplified Technical English).

What is STE (Simplified Technical English)?

It’s a limited and standardised subset of English, used in technical manuals in an attempt to improve the clarity of and comprehensibility of technical writing. See the Wikipedia article. It’s aim is to help the users of the English language understand technical documentation, particularly in international programs which include people whose first language is not English.

The set of rules that you use to write Simplified Technical English is defined in the manual: ASD-STE100. The rules are not static. They are changing, but the aim is to produce a stable base.

One of the aims is to avoid the need for translations, although it also helps with doing translations. (The latter was not the original goal.)

What’s wrong with everyday English?

Lyneve ran through the aspects of English that make it difficult for people to understand in technical manuals. For example, different areas of the world use different variations of English. We use different language on different media. There are complex grammar structures, plentiful synonyms, and more.

Core skills and competencies

Most clients of TechWriter Placement and Services (where Lyneve works) ask for:

  • Strong collaboration skills, including communication, time management, positivity and adaptability.
  • The ability to write strong plain language.
  • Knowledge of tools, especially Microsoft Word.

What do need to know to be able to write in Plain English and in Simplified Technical English? Lyneve compared the principles and rules of the two.

The STE rules are based on a good knowledge of grammar. For example, you need to know what verbs, nouns, participles and adjectives are, and be able to identify the grammatical subject and object of a sentence. For example, “Convert nominalised actions into verbs”. Many Australians don’t know the language of grammar, although they know how to read and write very well. Whereas people coming from non-English-speaking countries have the opposite problem: they know the grammar very well, but can’t necessarily read and understand English.

Thus, using the STE specification requires a high standard of professionalism on the writer’s part. Organisations can choose to train existing staff, install automated an checking system that checks the language (as used by Boeing, for example), and perhaps employ contractors. STE is not in much demand in Australia.


Thanks Lyneve for an authoritative and interesting introduction to STE. I loved the contextual information Lyneve included in this session.

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.


Get every new post delivered to your Inbox.

Join 1,497 other followers

%d bloggers like this: