Blog Archives

WritersUA 2011 – Using social media to get readers involved

This week I attended the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. On Tuesday it was my turn to present a session, called “Getting your readers involved in the documentation”. This post summarises my talk and offers you the opportunity to download the presentation in PDF form.

At Atlassian, we’ve been using social media in various ways, to make our documentation a living, interactive hub where people can find the answers to their questions, talk to us, talk to each other, and use the documentation as a tool to help each other.

Download the presentation

If you like, you can download a copy of my presentation in PDF form. I’ve put a lot of information and references into the speaker’s notes too.

What’s in this post

The rest of this post is a summary of and discussion of my presentation, and of the condensed version that I showed people at the WritersUA peer showcase.

The social organisation

We know that organisations are becoming more social. Studies show that engaged customers buy more, are more likely to be satisfied with the product, and are more likely to help each other use the product.

In the same way, I’d like to propose that engaged readers will keep coming back to the documentation, are more likely to be happy with the documentation, and will use the docs as a tool to help each other.

The tools

The tools and ideas I discussed are:

  • Using a wiki as the documentation authoring and publishing tool – Confluence. In our documentation and in my presentation I’m using Confluence wiki. But most of the tools and ideas are transferable to online documentation on any platform.
    • Allowing readers to add comments to the documentation pages.
    • Allowing various groups of people to edit your documentation, including community authors, all the company staff, customers, the whole wide world.
    • Using wiki permissions to determine who can do what.
    • Monitoring the updates via RSS feeds and wiki watches.
  • Designing a contributor licence agreement, based on the Apache Contributor License Agreement, to protect the rights of all parties.
  • Adding a Creative Commons copyright licence to the documentation pages. Ours is a Creative Commons by Attribution licence, which means that anyone can use the documentation for any purpose they like, provided they acknowledge us as the source.
  • Using a web service that allows you to design an online feedback form, then grab the HTML to embed the form into your own documentation page – Wufoo. When people fill in information on your form, the data goes into the Wufoo database. You can then log in to Wufoo and see the results, get some statistics, and so on.
  • Linking to blog posts written by community developers and authors from within your documentation. For example, the JIRA Tips of the Trade, the Crowd Tips of the Trade and the Confluence Tips of the Trade.
  • Encouraging people to interact with your documentation via Twitter (Twitter.com).
    • Using Twitter as a medium for your release notes.
    • Encouraging people to tweet hints and tips about your products, and then taking it a step further and embedding a live stream of tweets on a documentation page. See the JIRA Tips via Twitter and the Confluence Tips via Twitter pages.
  • Rewarding contributors by giving them an online badge that they can add to their blogs or other social sites.
  • Organising a doc sprint. This is an event, similar to the book sprints of the opensource world, where a group of people get together for a specific period of time to write a specific set of documentation. We have held two doc sprints, with participants working in our offices and remotely all over the world. We plan to hold more.
  • Bringing back fond memories of a documentation-related event, and encouraging people to join in next time, by streaming photos of the event onto your documentation page directly from Flickr. Flickr is a web service where you can upload and share photographs with your community, friends and the world.
  • Building fun, a game, a challenge and interactivity into your documentation. I demonstrated at the Dragon Slayer documentation.

The Dragon Slayer Documentation

The Dragon Slayer documentation is a set of installation instructions that we created to solve a specific problem. Atlassian, the company I work for, has a great set of products that you can set up to work together as an integrated development suite. At the moment, though, the integration process is long and complex. In fact, it’s painful. The products were not originally created to work together, and we’re developing the integration incrementally. The setup process is getting easier all the time, because our developers are working to improve the process.

In the meantime, we needed some documentation that leads people through the setup process, to create a specific environment with some good simple examples of the integration possibilities. This documentation does not replace the existing installation and upgrade guides for each product. Instead, it’s an additional tool to get people started quickly when they want to set up the full suite of products.

What’s more, because the process is long and complex, we wanted to turn the pain into fun. So we challenge people to come a slay the dragon. The dragon is, of course, the setup process.

A summary of the Dragon Slayer docs:

  • There are 9 stages, corresponding to 9 pages. Each stage consists of many steps.
  • We’ve taken pains sure ensure that the fun stuff is at the top and bottom of the pages. In between is good, solid technical writing – “how to” steps that we test rigorously, end-to-end, before making any updates, to ensure that the entire environment will work.
  • There’s a pretty picture and some funny words (shamelessly cribbed from various online translations of Dante) at the top of each page.
  • At the bottom of each page, we congratulate you on your victory and tell you what you have achieved so far.
  • When you start out on the dragon quest, you meet Sir Charlie of Atlassian, whom you will recognise as the dude in the Atlassian logo. He is scantily clad and has only a staff to ward off the dragon.
  • As you go through the stages, Charlie acquires armour and a sword, so that he is well equipped by the time he meets the dragon in stage 9.
  • When you finish the dragon quest, you get a T-shirt. (A real one.)
  • During the quest, you can intereact with other dragon slayers via Twitter. We’ve crafted some funny tweets that are a call to action. If you click the “Tweet” link, we prepopulate your tweet box with those words. You can delete or change them before tweeting. We also embed a live stream of tweets on the Dragon Slayer front page, so that people can see which dragon slayers are out there right now.
  • Each page also has a number of links to the dragon slayers’ forum, where you can discuss any problems you encounter and swap ideas with other people going through the procedures at the same time as you.

The plan is that the Dragon Slayer documentation will morph into a set of quick, simple steps. The dragon may disappear entirely. Or maybe not. Watch this space. 😉

The WritersUA peer showcase

I presented a condensed version of the presentation at the WritersUA peer showcase on the last day of the conference. What happens at the peer showcase is that you sit at a table for two hours, and people drop by in groups or individually to see your project. So you need just a short demonstration. I focused on our use of Twitter in and around the documentation, and specifically on the Dragon Slayer documentation.

I was completely overjoyed when I won the award for the most innovative peer showcase project at the 2011 Conference for Software UA. Thank you so much to everyone who voted for our project, and to Atlassian for giving the technical writers the opportunity to do such fun stuff in our documentation.

WritersUA Peer Showcase trophy

Bye

I hope you find the attached presentation useful. Let me know what you think, and if you’re doing something similar.

WritersUA 2011 Tuesday – HTML5

This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. On Tuesday I attended two sessions on HTML5. The first was a presentation by Scott DeLoach, called “HTML5 to the Point“. The second was a hands-on session run by Char James-Tanny, called “60 minutes to an HTML5 Web Page“. This blog post is derived from the notes I made during those two sessions. If you find any inaccuracies, they’ll be mine.

First, here are my notes from Scott‘s session. He presented a lot of highly technical information. Thanks to his easy, clear way of presenting information, we absorbed it all.

Why is HTML5 important?

Scott introduced his topic by telling us about the organisations that are already using and indeed driving the adoption of HTML5:

  • According to W3C, HTML5 is the future of the web. It will replace the existing versions of HTML and XHTML.
  • Adobe are working on “Helium” (we’re not sure exactly what this is yet) and “Wallaby” (allowing you to save Flash files as HTML5).
  • Facebook will be spending the bulk of their investment and development on HTML5 this year.
  • Google is hugely into HTML5. Leading the way. The Google Instant search uses HTML5. Gmail is coded in HTML5. See their site HTML5 Rocks. Some of their features work only in Chrome, but others work in other browsers too.
  • Microsoft: Bing is using HTML5.
  • Apple rewrote all of the Apple website in HTML5.
  • YouTube: Video is one of the biggest parts of HTML5, and YouTube are moving their video format to HTML5.
  • Netflix is moving to HTML5. The conversion is almost complete.

Converting to HTML5

Scott listed the basic steps required to convert a web page to HTML5:

  1. Use the HTML5 doctype.
  2. Replace HTML elements that are no longer supported in HTML5. Some of the features that have been deprecated for a while are now not supported.
  3. Prepare to support older browsers (requires a bit of trickery) and mobile devices (easy).
  4. Use the new structure elements provided in HTML5. Take advantage of the new tags to structure your documents.
  5. Use the other new features. There are some really cool things you can do. HTML5 offers a combination of standardising the things we’ve been doing anyway, with some new features too.

The HTML5 doctype

They have simplified the format of the doctype statement that you put at the top of your file.

At its simplest, it’s just this:

<!doctype html>

For the more extended format there are two options, an HTML syntax and an XHTML syntax. The difference between the two is tiny, just in the format of the quotation marks. You can choose either one.

Unsupported elements

Scott showed us a list of elements that are no longer supported, and their HTML5 alternatives.

The list is fairly long. Here are just a few specific examples:

  • center – use CSS (text-align:center)
  • frame, frameset, noframes – use an iframe or CSS (float properties)
  • noembed – use the “video” element

Supporting older browsers

Scott pointed out that we will need to support older browsers, and in particular IE 8 and earlier. (The latest version of IE, which came out yesterday, has much better support.) Scott gave us some tips:

  • There are a number of new elements that the old browser will not recognise. You will need to add a style definition for each of the new elements, that the older browser can pick up. Examples of such new elements: article, aside, canvas, details, etc.
  • Test your pages in the old browsers.
  • Create styles specifically for older browsers.
  • For older versions of IE, use Remy Sharp’s script to enable all the new elements in older versions of IE.

Supporting mobile devices

Most browsers for mobile devices (generally Safari and Chrome) support HTML5.

Structuring your documents

This is one of the biggest changes, and also most interesting to technical communicators. You can use the new elements in HTML5 to structure your documents more easily.

Scott listed all the new elements, and homed in on a few examples:

  • header – A logo and page title.
  • nav
  • section – A collection of news articles. You can nest sections. Note that if you do that, the heading levels may change automatically. For example, let’s assume that you nest section B inside section A. If section B has an h1, that h1 will change to h2.
  • article – A blog post or news article. Scott pointed out that section and article have a lot of overlap. This will probably confuse people. An article is something that can stand alone. A section does not really stand alone.
  • aside – Scott mentioned that this is a good placeholder for “related topics” links.
  • footer

Scott showed us a neat diagram illustrating how each of the above elements might fit into a page. Then he dragged the elements around, showing how flexible the structure is. It’s largely up to you, how you use the elements to structure your page.

Other elements

Including video and audio is a lot easier, using the “video” and “audio” elements.

The “canvas” element is really cool. It creates an area for images and shapes. It’s an alternative to having a graphic, a way to draw shapes (squares, circles) using code. You can have elements of the graphic animated or move around.

The “ruby” tags add pronunciation guides to content.

The “wbr” tag offers an opportunity for a linebreak. If a linebreak is necessary, the browser can make one.

New global attributes

Scott mentioned a few of the new attributes available in HTML5:

  • It’s easier to make menus via the “contextmenu” attribute, which creates a popup menu.
  • draggable” allows an element to be moved.
  • spellcheck” checks the spelling in the element.

New methods

Scott discussed a number of new methods. I didn’t take detailed notes here.

Many, many new events

Scott said, what’s really great is that HTML5 standardises a lot of events that were previously supported only by specific browsers.

Some examples:

  • onwaiting – you could provide some entertainment while people are waiting. 😉
  • oninvalid – to provide an error message in a form.
  • onoffline and ononline – you can tell people they won’t be able to find the information because they can’t access the web.

New form elements

Scott walked through a few of the new form elements:

  • required” to mark required fields on a form.
  • Built-in validation for certain types of input fields, with built-in error messages. For example, if you specify an input field with ‘type=”email”‘, then the browser will validate the input content as an email address. At the moment, there are few browsers that support this option.
  • You can also write your own custom validation and error messages for user input, using “input-pattern“.

Examples

For the rest of the session, Scott showed us some examples of the features he had mentioned.

  • We saw the spellcheck in action. Pretty cool. The browser drew a squiggly red line under the misspelled user input.
  • Including video, via the “video” element. Two great things in HTML5: It’s much easier to code the inclusion of the video, and you can also include multiple source files (for example, of different formats) so that the browser can choose the one it recognises. For mobile devices, for example, you can specify a minimum device width for your video. You can also include .swf files in the video element. If you include the attribute “controls“, the browser will include video controls too.
  • The “ruby” element lets you provide pronuncation guides. The phonetic text appears directly above the word(s) bracketed by the “ruby” tag. Actually, Scott pointed out, the use of the tag is not limited to providing pronunciation guides. You could use it to provide a translation, or anything else.
  • Determining the user’s location. Scott showed us a script that figures out your latitude and longitude. (He also has one that determines your altitude.) Let’s say a plumber is going out to fix a boiler. You can figure out which boiler they’re at and show them the correct “how to” video for that boiler.
  • Using the new “editable” and “save” features in HTML5, you can let people annotate a web page.

Sample sites and other resources

Scott showed us a number of resources, including development applications, sample sites, recommendation sites and information about browser support.

I didn’t make notes of all the sites Scott recommended. I’m sure he’d be happy to provide them. 🙂 Here are just a few that he highlighted:

  • Adobe Dreamweaver CS5 can write HTML5. So can CoffeeCup’s The HTML Editor 2010, and TopStyle 4.
  • Scott recommends specifically the following two sites, written entirely in HTML5
    • MTA.ME, a subway train visualisation.
    • The Wilderness Downtown. Awesome, says Scott. It asks you to enter the address of the town where you grew up. (Just start typing the name of the town, anywhere in the world. The smart search will find it and prompt you!) It’s spooky. They go behind the scenes, using Google Maps, and put the location up on the screen. Then the action starts, with the guy running near the location that you specified! (Chrome browser recommended.)

Scott’s quick reference guide to HTML5

Scott has created a quick reference guide to HTML5, which he made available specifically to WritersUA attendees. He said it’s fine to include the link in this blog post 🙂 so here you are: HTML5 quick reference, a PDF document by Scott DeLoach.

Introduction to Char’s session

The rest of this post comes from the notes I took during Char‘s session. Char hosted a hands-on lab, where we built an HTML5 web page from scratch.

To start off her session, Char gave us some introductory information about HTML5 syntax.

HTML5 syntax

HTML5 has a free-form syntax:

  • Any case (upper, lower, mixed)
  • Double quotes, single quotes, no quotes
  • Close tags or no close tags
  • Optional attribute values.

doctype

<!doctype html>

That’s all you need in your doctype element, to make a document HTML5!

Page structure

The page structure is familiar to anyone who has created an HTML page:

<!doctype html>
<html lang="en">
<head>
</head>
<body>
</body>
</html>

Hands-on exercise

We started by creating a file “index.html”, containing just the page structure elements shown above.

Then we added the following code to the “head” element:

<meta charset="utf-8">
<title>I Need a Title!</title>
<!--[if lt IE 9]>
<script src="http://html5shim.googlecode.com/svn/trunk/html5.js">
</script><![endif]-->
<link href="css-wua.css" rel="stylesheet" type="text/css">

The first script element pulls in Remy Sharp’s script to declare the new HTML5 elements for compatibility with IE8 and earlier. This is the same script that Scott told us about, just hosted in a different location.

The second script elements includes a stylesheet, created by Char, to make things pretty.

For the rest of the session, we added the HTML body to create a simple web page. I haven’t included it in this post, because it’s Char’s work. Here is an online version of the page we created.

My conclusion

Thank you Scott DeLoach and Char James-Tanny for two interesting and authoritative sessions. I love Scott’s quiet, composed way of presenting so much technical information so easily. Char is absolutely great and guiding a motley collection of HTML5 wannabees through the fumbling stage up to producing a quality HTML5 page. It was useful to have Char’s session follow on from Scott’s. Again, what a great conference this is. 🙂

WritersUA 2011 Monday – Design and tools for eLearning

This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. These are my notes from the session called “Determining the Best Design Approaches and Development Tools for eLearning” presented by Joe Ganci. If you find any inaccuracies, they’ll be mine.

Joe’s presentation style is conversational, easy and comfortable. He walks right up to the audience, asks them questions and tells them personal anecdotes to illustrate his points.

First points to consider

There are four things to consider when determining your design approaches and your choice of development tools for an eLearning system:

  • Talent – Who is your talent? Who does the work?
  • Topic – What do you want to teach people, and who is your audience?
  • Technique – What technique are you going to use to impart your information?
  • Tool – Determine the tool or tools after all the other questions are answered.

For the rest of the session, Joe dived deep into each of the above points, and showed how your choices will influence the tools that you choose.

Talent

Who does the work? Consider these three groups of people:

  • Instructional designers
  • Subject matter experts (SMEs)
  • Programmers

At the beginning of a project, the instructional designer creates a number of deliverables, including the storyboard, design document and analysis document.

Subject matter experts are well known to technical writers.

When considering the programmers, ask these questions: Who builds the eLearning in your organisation, and who should it be?

How does talent impact tool selection? SMEs, instructional designers and programmers will be using different tools. Joe showed us how the different groups of people are comfortable with different tools. For example, SMEs may use presentation tools like PowerPoint, instructional designers may use Camtasia, programmers use things like XML, HTML, Flash.

Topic

Looking at the information you want to impart, there are four key areas:

  • Information (concepts)
  • Compliance
  • Technical information
  • Soft skills (highly scenario-based)

Questions to ask yourself: Which of those information types are the most requested within your organisation, and who works on them?

How does topic impact tool selection? For informational topics, presentation tools like PowerPoint and Prezi are useful. For compliance topics, you may choose Camtasia or Lectora. For technical information, something like Raptivity, SmartBuilder. For the soft skills, you need a lot of computing: XML, HTML, Flash.

Technique

Joe discussed four kinds of technique in eLearning systems:

  • Tell me
  • Show me
  • Let me
  • Test me

Moving from top to bottom of the list, these techniques require an increasing level of complexity in the instructional design.

Questions to ask: What techniques are your favourite for eLearning, and which techniques do you want to implement next.

One of the audience members said he prefers a combination of “show me” and “let me”. Joe agreed. You don’t want to overdo the “let me” side of things.

It’s sometimes a good idea to be able to present each candidate with a slightly different experience.

When testing the student, one technique is to set up a pool of questions, and have Captivate randomly select questions out of the pool. You can base the pools on level of complexity, to ensure that each candidate gets the same overall level of test.

Essential questions for determining your design approach

Joe took us through each of the following questions that we need to ask, and discussed the various options for each.

  1. What is the content? (Your objectives, lesson plan, time available to the learner, existing content that you can base yours on.)
  2. Who is the audience? (Age, prerequisite knowledge, language, culture, disabilities, educational level, and so on.)
  3. How will you design the material? (Rapid prototyping, or the traditional instructional design approach, or a combination of the two.)
  4. What is necessary for the design? (How much time is necessary, do you need a video, do you need audio, how much text is required, how much interactivity, and so on. A number of the answers depend on you audience as well as the topic. The answers to these questions affect your choice of tool.)

How does technique affect tool selection? For “tell me”, the presentation tools like PowerPoint are effective. For “show me” and “test me”, you may use Smartbuilder and similar tools. For “let me”, you will need HTML, XML, Flash, and so on.

Questions to consider: What tools are available to your organisation, and what tools do you know? You need to consider also how well you know a tool, and whether you know everything that you need to know.

The tools

There are a number of tools, and many of them do similar things. But they don’t all work the same way. There are some really good surveys out there. Joe pointed out the survey of the Top 100 Tools for Learning 2010.

Interestingly, the tools at the top of the list are things like Twitter, YouTube, GoogleDocs – social and informal learning tools.

As a trend in the next 3 years, Joe sees more and more hand-held platforms.

How does all this affect developers of eLearning?

We will be basing our work on the known foundations, but we’ll be looking at new ideas and techniques too.

An example of eLearning developed by Joe

Joe showed us an eLearning tool that he created in Captivate. It’s aim is to train hotel clerks in dealing with conflict. It’s available on the web: Hotel Clerk Training, Dealing with Conflicts. (Make sure you have audio enabled on your computer.)

It’s pretty cool. You can hover over each person, such as the manager or coworker, to see what each person says when you (the clerk) ask them what to do.

There’s a bit of humour in it, especially in the acting on the video segments – enough humour to make you smile, and enough to make you sympathise with the people.

When the user chooses the right response, the system responds with some jubilant animation to reward them.

Why is this type of approach better than PowerPoint? The student who is already an expert can fly right through the lesson without wasting time. A novice can explore all the answers in full. It’s also more interesting and more engaging. An experience as close to real life as possible is more likely to put the learning into your long term memory, as opposed to short term memory.

My conclusion

Thank you Joe for an interesting and engaging approach to the choice of tools for eLearning. It’s very useful to see how our decisions can affect the tools we choose, and how indeed we should make other decisions before deciding on a tool. I love the hotel clerk training tool!

WritersUA 2011 Monday – Adobe RoboHelp’s commenting feature

This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. One of the sessions that I attended today was an Adobe lab, run by Scott DeLoach, Kevin Siegel, Laurie Edelman and others.

During the conference, there were a number of “lab” sessions. The labs offer a number of computer workstations and software that we could use for hands-on experimentation. A few experts wandered around offering help and advice.

My aim in attending the Adobe lab

I decided to take a look at the latest version of RoboHelp. I have used RoboHelp extensively in the past, but not since RoboHelp 8.

In particular, I wanted to explore the new features in RoboHelp that allow you to gather feedback from users, and allow users to share comments among themselves. I had heard and seen this demonstrated in various places. The idea is that you have an online help system, shared amongst your users, even installed individually on their machines. Each user can add comments to their own version of the help, and share those comments with other users via a central server.

Exploring RoboHelp’s comments feature

In the lab there was no RoboHelp Server available, so we could not see the server side of the functionality in action. But I did manage to explore how it would work. Here’s what I did.

In RoboHelp, create your online help topics as usual. For the lab session, I used one of the sample projects supplied by Adobe.

The next step is to generate your help output, selecting Adobe Air as your output format. The Adobe AIR output is the only format that supports comments submitted by users. To generate the AIR output:

  • Choose one of the a “single source layouts” available. A single source layout basically corresponds to an output format. For this lab session, a few Adobe Air layouts were available. I chose “Adobe AIR – Role Based”.
  • Double-click the layout in the “single source layout” window. You get a popup where you can configure various options for the chosen layout.
  • On the “General” tab, choose an “Output Type” of “Adobe AIR Application“. This is the only output type that will allow comments from users. The other output types are hybrids that weave a Flash solution into an HTML web-based help system.
  • You will need a digital certificate. If you don’t have one (which is likely at this point!) you can generate a self-signed certificate for use while testing. Eventually you will need to get a certificate from a real certificate authority (CA). To generate a digital certificate, click “Create” next to “Digital Certificate”.
  • Supply a publisher name of some sort.
  • Specify a password for the certificate.
  • Next to “Save As”, specify a path and name something like “C:\cert.p12”.
  • Click “OK” to generate the certificate.
  • Click the “Collaboration” tab.
  • Select “Enable Topic Rating”, “Enable Commenting” and “Enable Comment Moderation”.
  • Set a password that the comment moderator will use.
  • At this stage, it would be good to specify the RoboHelp server to enable server-based storage and sharing of comments. I could not do this during the lab, because there was no RoboHelp server available.
  • Click “Save and Generate” to create your online help system.
  • Click “View Result” to see the resulting help files.

The AIR application will start up, showing your help topics in the help system. Now you want to add a comment to a topic.

  • Click the comment icon near the top left of the screen. (The icon looks like a couple of comment bubbles.)
  • A comment area will appear at the bottom of the topic.
  • To add a comment, click the plus sign.

Adding a comment:

Adobe RoboHelp's commenting feature

Adobe RoboHelp's commenting feature

Comments are displayed in reverse chronological order:

Adobe RoboHelp's commenting feature

Adobe RoboHelp's commenting feature

My conclusion

This looks pretty cool. As far as I could see, there’s no opportunity to add graphics or formatting to the comments. They’re plain text. Also, they’re not threaded – you can’t reply to a specific comment. Still, once a server is hooked up it is pretty cool for people to be able to share comments from their desktop apps. I’d be interested to see it in action, and to hear any experiences other technical writers may have had with this feature.

WritersUA 2011 Monday – Hotrodding your online help

This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. These are my notes from the session called “Hotrod My Help” presented by Leah Guren. If you find any inaccuracies, they’ll be mine.

Leah’s presentation style is both informal and professional. She started out by introducing herself as “this deranged woman”. She then became more serious quite quickly. Her talk was about design of online help systems. She used the metaphor of hot rodding – talking about the paint rather than what’s underneath.

Introducing the topic

Leah’s talk was entirely tool agnostic, and described techniques that we can apply to our documents with very little effort.

Nevertheless, Leah pointed out, this stuff matters for a number of reasons:

  • Design should match the subject matter.
  • Better design improves usability.
  • We’re not talking about making things look pretty. We want to make sure that what we develop will communicate as effectively to users as the words we choose.
  • When people see help with a sloppy design, they’re less likely to trust the information.
  • Design should support the meaning of the content.
  • It should make it easier for people to find what they’re looking for, to recognise it and to use it.

Leah also pointed out that if your readers are noticing the design, then you have made a mistake. (As a side note, I tweeted this point and received an interesting reply from Bill Kerschbaum.)

The design concepts

Leah introduced us to some design concepts, the jargon. Mastering the terminology lets you defend you choices with more authority.

Leah introduced us to the acronym PARCH:

  • Proximity – When elements are close together, we recognise that they are related.
  • Alignment – Choose where you position elements on the screen, to develop a meaningful design.
  • Repetition – Repeated visual patterns help people to access and remember the information efficiently.
  • Contrast
  • Hierarchies and dependencies

Proximity

One stylistic mistake that violates this principle is the “floating heading”. That’s when you have a heading with the same amount of space above it as below it. Instead, there should be less space below the heading, to bring it closer with the content it describes.

Alignment

Use alignment for a less sloppy design.

Repetition

Consider things like colours, icons, placement.  Stylistic repetition reinforces the information for the user and gives them more confidence.

Contrast

We need contrast so that people can see the differences in meaning between different elements on the page. For example, links should look different from other text. So should headings, and layered information. The rule of contrast is that it must be meaningful. Readers don’t care how you do it, whether you use a list or headings or bold text. Just be consistent and make it meaningful.

Hierarchy

This defines how elements of information on the page are related to other elements on the page. Consider the use of white space and indentation.

Other concepts and techniques

  • White space – Consider margins, space between lines, hanging indents, paragraphs etc. White space is critical. If you don’t have enough white space, the text is not readable. Users flee from densely-packed screens.
  • Plumb lines – Draw vertical lines at every point where an information element starts, to make a clean design. Good clean design steps into the background. Bad design is noisy.
  • Indents and text wrap – Indents help the concept of contrast. Good examples are bulleted lists.
  • Paragraphs – Leah recommends the following design techniques for paragraphs, to enhance readability:
    • Flush left, ragged right.
    • Single line spacing.
    • White space between paragraphs.
  • Chunking – Use white space intelligently, to show the logical visual chunks of information.
  • Nesting – Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting. The rule in technical communication (a tacit contract with the user) is this: if I’m going to break the information down into logical categories, there must be more than one category. For example, you can’t have just one item in a bulleted list, or just one level-2 heading.

Examples – applying the concepts

After introducing all the theory, Leah moved on to examples of web page makeovers, using her hotrod metaphor. She took us through some real documentation and web pages from various sites, and applied her principles to each one.

These are some of the mistakes she fixed up:

  • Messy text.
  • Dashboard that was not designed to be meaningful.
  • Screenshots taken without care and without tidying up afterwards.
  • Sloppy text wrap, that probably happened when pasting content from elsewhere.
  • Inconsistency in capitalisation, punctuation, and so on.
  • Long lines that force the user to do horizontal scrolling. A typical culprit here is information in tables. This is easy to fix, but easy to overlook.
  • No visual cue that content continues below the fold. Readers may think they have reached the end of the steps, without realising they need to scroll down. One way to fix this is to include a “Start” and “End” icon.
  • Help window opening on top of the application by default. The solution is to make the default opening position at top right, for example.
  • Concordance (repetition of same words) in the table of contents (toc). This is very distracting. If the toc entries are very long, people will not see the meaningful bit in the toc window.
  • Use of blue (usually used to denote hyperlinks) as an emphasis or point colour.
  • Too many layers of hierarchy (too much nesting) in a table of contents.
  • Links in the text. Don’t put links in the text unless they’re popups or dynamic HTML. Keep all links off to the side or at the bottom. People get distracted by links, or click them and get lost.
  • Empty topics.

Help authoring tools

If the problem we’re addressing lies within a tool that we use to develop help systems, then the HAT and DITA tool developers need to fix it. We need to be involved in the design of such tools.

My conclusions

Throughout the presentation, Leah had “bonus rounds” where she asked us to name concepts that the pages were violating. She promised us “valuable prizes” (said with a grin) which we could collect afterwards. This was great for getting audience participation going.

Thank you for a lively session, Leah!

Hotrod My Help
=============
Leah Guren (Cow TC) 

http://www.cowtc.com/

Leah started out by introducing herself as “this deranged woman”. Herpresentation style is informal and easy. She then got more serious quite quickly. She does many presentations about tehcnical communication. Today she will talk a lot about deisng. Use the metaphor of hot rodding – talking about the paint rather than what’s underneath.

Everything she will talk about is tool agnostic. These are techniques that you can apply to your documents with very little effort.

This stuff matters because the design should match the sujbect matter. Better design improves usability. we’re not talking about making things look pretty. We want to make sure that what we develop will communicate as effectively to users as the words we choose.

When people see help with a sloppy design, they’re less likely to trust the information.

If your readers are noticing the design, then you have made a mistake.

Good design follows a series of rules.
Design should support the meaning of the content.
It should make it easier for people to find what they’re looking for, to recognise it and to use it.

Leah introduced us to some design concepts – the jargon. Mastering the terminology lets you defend you choices with more authority.

Leah introduced us to a new acronym: PARCH:
* Proximity – When things are close together, we recognise that they are related.
* Alignment – Choose intential places to position elements on the screen, to develop a meaningful design.
* Repetition — Repeated visual patterns help people to access and remember the information efficiently.
* Contrast
* Hierarchies and dependencies

Proximity:
==========
One stylistic mistake that violates this principle is the “floating heading”. That’s when you have a heading with the same amount of space above it as below it. Instead, there should be less space below the heading, to bring it closer with the content it describes.

Alignment
=========
Less sloppy design.

Repetition
==========
Consider things like colours, icons, placement.

Stylistic repetition reinforces the information for the user and gives them more confidence.

Contrast
========
We need contrast so that people can see the differences. For example, links should look different from other text. So should headings, and layered information. The rule of contrast is that it must be meaningful. Readers don’t care how you do it, whether you use a list or headings or bold text. Just be consistent and make it meaningful.

Hierarchy
===========
This defines how elements of information on the page are related to other elements on the page. Consider the use of white space and indentation.

Other concepts:
==============
* White space — Consider margins, space between lines, hanging indents, paragraphs etc. White space is critical. If you don’t have enough white space, the text is not readable. Users flee from densely-packed screens.

* Plumb lines — Draw vertical lines at every point where an information element starts, to make a clean design. Good clean design steps into the background. Bad design is noisy.

* Indents and text wrap — Indents help the concept of contrast. Good examples are bulleted lists.

* Paragraphs — Leah recommends the following design techniques for paragraphs, to enhance readability:
** Flush left, ragged right.
** Single line spacing.
** White space between paragraphs.

* Chunking — Use white space intelligently, show that we’re showing logical visual chunks of information.

* Nesting — Nesting relates to hiearchies and logically related information. Leah mentioned “illegal” nesting, which all of us do. The rule in technical communication (a tacit contract with the user): if I’m going to break the information down into logical categories, there must be more than one category. For example, you can’t have just one item in a bulleted list, or just one level-2 heading.

Examples – applying the concepts
========

With the theory out of the way, Leah moved on to examples of makeovers, using her hotrod metaphor. She took us through some real documentation and web pages from various sites, and applied her principles to each one.

Some of the mistakes she fixed up were:
* Messy text.
* Dashboard that was not designed to be meaningful.
* Screenshots taken without care and without tidying up afterwards.
* Sloppy text wrap, that probably happened when pasting content from elsewhere.
* Inconsistency in capitalisation, punctuation, and so on.
* Long lines that force the user to do horizontal scrolling. A typical culprit here is information in tables. This is easy to fix, but easy to overlook.
* No visual cue that content continues below the fold. Readers may think they have reached the end of the steps, without realising they need to scroll down. One way to fix this is to include a “Start” and “End” icon.
* Help window opening on top of the application by default. The solution is to make the default opening position at top right, for example.
* Concordance (repetition of same words) in the table of contents (toc). This is very distracting. If the toc entries are very long, people will not see the meaningful bit in the toc window.
* Use of blue (link colour) as a highlight colour.
* Too many layers of hierarchy (too much nesting) in a table of contents.
* Links in the text. Don’t put links in the text unless they’re popups or dynamic HTML. Keep all links off to the side or at the bottom. People get distracted by links, or click them and get lost.
* Empty topics.

Help authoring tools
====================

If the problem lies within a tool that we use to develop help systems, then the HAT and DITA tool developers need to fix it. We need to be involved in the design of such tools.

My conclusions
==============

Throughout the presentation, Leah had “bonus rounds” where she asked us to name concepts that the pages were violating. She promised us “valuable prizes” (said with a grin) which we could collect afterwards. This was great for getting audience participation going.

Thank you for a lively session, Leah!

%d bloggers like this: