AODC 2009 wrapup

Last week I attended the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. This is the second year that I’ve been to this conference, and I highly recommend it for anyone interested in technical writing or communication.

A big “thank you” to the AODC organisers, and especially to Tony Self, Penny Bradley and Mick McMahon. The conference ran without a hitch. It’s worth attending just for the social events and networking. As a bonus, the speakers and sessions were interesting too

There were 19 sessions in total. I have blogged about some of them:

• Pattern language for information architecture
• Content, standards, learning and SCORM
• Delivering enterprise software documentation on a wiki
• Design of context-sensitive help
• Translation and localisation
• Single source publishing
• Structured authoring
• Stump the panel
• Enabling feedback and collaboration in online help systems
• What if the reader can’t read?

Melbourne

Never been to Melbourne? Neither had I. It’s a fun city, and quite different in character to Sydney. The AODC conference happened at the Vibe Savoy hotel. Here’s the view from my hotel window, overlooking the Southern Cross Station out towards Docklands:

AODC 2009 wrapup

Here’s the GPO and a Melbourne tram:

AODC 2009 wrapup

Next year’s AODC

I’ve heard that AODC 2010 will be in Darwin. I haven’t been there yet either. Hope to see you there

Mick McMahon

AODC day 3 – Pattern language for information architecture

Last week I attended the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. This blog post is part of a series about some of the AODC sessions I attended.

Here are some notes I took from the session on a pattern language for information architecture, by Matthew Ellison. I hope these notes are useful to people who couldn’t be at the conference this year.

Pattern Language for Information Architecture

Matthew introduced pattern languages by saying that they may give you a practical way of capturing the techniques that work for you — a way of documenting the golden rules.

A pattern language is a structured method for describing good design practices within a specific field. Michael Hughes has done a lot of work on pattern languages in our field. Pattern languages establish a rule of thumb. They do not offer a rigid solution, but something you can use again and again when similar situations arise in a particular environments.

Pattern languages in architecture

Pattern languages were first developed about thirty years ago, originating in the architecture field. Matthew was very taken with Christopher Alexander’s book A Pattern Language: Towns, Buildings, Construction (1977). It even smells nice, says Matthew. The structure of the book, its pictures and diagrams, and the quaint language make it a book you can dip into and enjoy. It covers a wide field, from the design of towns down to the design of doorknobs.

Matthew showed us an example pattern from the book: “A Place to Wait”.

• The pattern starts with the problem: “The process of waiting has inherent conflicts in it.”
• Then it proposes the solution. As an example of the quaint language used: the pattern suggests that you should “…fuse the waiting with some other activity — newspaper; coffee; pool tables; horseshoes… where you can draw a person waiting into a reverie; quiet…”
• Then there’s a really cute little sketch of what a waiting area might look like.

Pattern languages for UI design

Another field that uses pattern languages is user interface (UI) design. Matthew showed us what such a pattern formula (template) might look like. Once again, they start with a statement of the problem, then tell you where such a pattern would be used. Next the pattern offers a solution and some form of illustration.

One such pattern in UI design is “Pagination”. Matthew showed us how the list of pages at the bottom of Google search and various other sites all fit this pattern.

Pattern languages for information architecture

What do information architects do? There are a few definitions. A good one is that information architects are responsible for the overall organisation of content.

How can design patterns help? They allow content providers to apply tested architectures to improve the user’s experience.

Matthew listed the following types of design patterns:

• Interface and layout (window and page layout).
• Structure of information and navigation dynamics (TOC, related links, popups).
• Content (information types, writing style and the way we assemble the content we write).

An example of an information architecture pattern: “Breadcrumbs”. The problem is: Users need to know their location in the document’s hierarchical structure, so that they can browse back to a higher level in the hierarchy. Matthew showed us some examples of breadcrumbs in various applications.

Suggested components of an information architecture pattern:

• The problem.
• Usage (where the pattern is used).
• The solution (a short bulleted list that describes the golden rule — fairly flexible and not too prescriptive).
• An illustration.
• The rationale (the reason why you would use this solution).

Matthew took us through some more information architecture patterns: “Content taxonomy”; “Signposting”; “Popups”. I don’t have any notes from this part of the session — I got too wrapped up in watching the examples. Matthew is sure to have the details

Examples

Michael Hughes proposed a design pattern for contextual help, to determine when and how we might use such help. Matthew showed us an example of embedded help from Microsoft Excel that conformed to the design pattern.

We looked at some design patterns in a few state-of-the-art online documents. One example is the UK Daily Telegraph online newspaper. Matthew discussed the design objectives of this site, and how they might relate to online documentation too. Notice the design elements, such as:

• Signposting and visual breadcrumbs, near the top of the page.
• Search, always at the top. Search is very important in all online newspapers.
• List of related articles.
• Related RSS feeds.
• Link to in-depth background information that supports the story.
• Pictures.
• Link to feature article.

Comparing a sports report and a current affairs item, they are visually and spatially very much the same. This makes it easy to use these newpapers online.

We also looked at a government site showing UK planning and building regulations. It also has a standardised pattern, with each element in a predictable place.

How can we define our design patterns?

Matthew suggests the following steps:

• Create your pattern statements (problem, usage, solution, rationale, etc).
• Decide whether the pattern statements fit into a style guide.
• Decide whether to enforce your patterns, e.g. by building them into an XML schema or DTD.

There are different opinions about whether a design pattern would fit into a style guide. IBM talks about enforcing your design patterns in structured authoring via XML, e.g. as DITA topic specialisations or map domains.

Thank you for another very cool and informative presentation, Matthew.

AODC day 3 – Content, standards, learning and SCORM

Last week I attended the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. This blog post is part of a series about some of the AODC sessions I attended.

Here are some notes I took from the session on content, standards, learning and SCORM, by Allyn Radford of Learn’ilities’. I hope these notes are useful to people who couldn’t be at the conference this year.

Content, Standards, Learning and SCORM

Allyn started by giving us some context of what is happening right now. Within content domains, the key themes of the information age are being adopted: Modularisation, specialisation, integration and interoperability. Our communication is changing in volume, purpose and channels. The emphasis is more on collaboration and less on expert-to-novice teaching. And there’s a stronger emphasis on openness.

Allyn says we need to rethink the focus of reusability. Now we have to reuse content across disciplines, and we have to assume that the content’s destination is unknown.

Everything is 2.0 and everything is social. We are living in a mash-up world. As an illustration, Allyn walked us through parts of Mashable, The Social Media Guide. It’s like a directory of mash-up sites that combine different data sources to produce some interesting conclusions, statistics and visualisations. One of Allyn’s favourites is the fun mash-up called If I dig a very big hole, where will I end up?

What are the implications for learning systems?

We are looking at moving from monolithic learning applications to modular services, across different sources and services.

Learning content and organisational content should no longer be seen as two separate things. Marketing information, specifications, etc, can also be used in learning material or in brochures. So you start to develop a whole different appreciation of how you determine the value of content in your organisation.

Content is one of the most expensive things an organisation will create, compared to the technology systems that support that content.

There has to be a bi-directional relationship between three key things: The content, the process/practice used to create the content, and the technology infrastructure. Before you create content, you need to set up procedures for how that content will be maintained in the future.

What’s the role of standards in all this?

Interoperability, reuseability, maintainability — all the “ilities”. (Hence the name of Allyn’s company.)

Management of content is key. Traditionally in learning systems, not enough effort has been put into this.

Allyn showed us a list of standards related to LET (Learning, Education and Training). One of them is SCORM (Shareable Content Object Reference Model). Allyn listed these 6 key concepts that SCORM was designed to support:

• Interoperability
• Accessibility (different devices and locations, as needed)
• Reusability
• Durability (content must outlast changes in technology)
• Maintainability
• Adaptability

SCORM allows you to take courses from one learning system, where they were developed, and put them into other learning systems where required.

Granularity and reusability are interrelated. You need to consider reuse versus context. You lose context as your content become more granular. So you have to find the best mix for your environment, depending how important context is to you.

Allyn says that the problem with most existing standards is a “walled garden” attitude. This does not work well with the move towards open standards. There are significant costs to development and adoption of standards.  The “no-strings-attached” licensing is essential in LET standards.

Allyn works primarily with LETSI at the moment. The LETSI model is very open. LETSI does not develop standards, but works towards the adoption of available standards in learning technology and related fields like HR and Knowledge Management. It focuses on the interstitial work i.e. the bits that need to happen between the existing systems.

LETSI was asked to look at what “SCORM 2.0″ might look like, focusing on interoperability. They started reconceptualising what was actually happening, in the areas of learning activities, resources, people and competency frameworks. It turns out that SCORM 2.0 is nothing like previous versions of SCORM.

Nowadays, people in universities and schools are not locked into a particular learning management system. They’re using podcasts, the web, and a number of other tools. Part of what’s needed, says Allyn, is to implement software that coordinates the bits of content used.

• A new solution for content orchestration (sequencing of content, e.g. based on how the learner performs).
• Integration of training with policy or technical documents. Also integration of data for learning and non-learning purposes, and integration of social learning content.
• Integration with HR, SIS and enterprise standards (so that we know what type of learning the person needs, to do the job required).
• Incorporation of competency models.
• Support for new pedagogies (such as collaboration).

So a new infrastructure model may have a set of “resources” that are data stores such as published content, user information systems, competency store, and so on. Users will access the stores via portal interfaces and portal applications. It’s the mash-up idea. There will also be an external integration layer, to allow access to external content sources.

Open educational resources

We must differentiate between “open education” and “open educational resources”:

• “Open education” is the provision of educational experiences with few, if any, barriers to participation and often no cost.
• “Open educational resources” (OERs) are resources that can be used in learning under some form of open licence governing usage and adaptation. So you can include the open courseware into your learning system.

OERs improve access to educational content, e.g. in third-world countries like Africa. The aim is to reduce cost (text books are very expensive) and to improve quality (by pooling the knowledge of experts and taking the content that’s most relevant to your environment). This can be bad news to publishers of learning materials.

OERs are built to be reused, so that you can adapt and remix them to suit your needs. So it’s very interesting to look at OERs to see what’s happening with open learning at the moment.

Allyn emphasised that we need to have a structured content model in learning content, to support granularity (essential for content reuse) and interoperability (essential for mixing content).

One big problem at the moment is the editing and aggregation tools available. Allyn has used and reviewed a number of tools and has not found a satisfactory one yet.

XML is the appropriate format to support content and structure, ignoring presentation. Useful formats are CNXML (an open education resource format), DITA and others.

What can you do?

Next steps, particularly when considering co-operation between creators of technical documentation and creators of learning materials:

• Participate in common activities (e.g. LETSI).
• Be aware that your content may be used in ways and places you don’t know about.
• Write for broader reuse scenarios.
• Have a joint focus on reuse and interoperability.

Question time

Comment from the floor: “I don’t think it’s possible to re-use content. A lot of speakers at this conference have talked about it, but I don’t think it’s possible.”

Answer: Granularity is the key. Identify the content that is suitable for reuse. There’s no intention to reuse all content. When you write content in a narrative form, you are tied to writing in a particular way. But when you write structured, granular content, you’re not thinking about the presentation or where it’s going to be used. You concentrate on the content itself. That makes the content more reusable (where applicable).

Thank you Allyn for a very interesting presentation.

AODC day 3 – Delivering documentation on a wiki

This week I attended the 2009 Australasian Online Documentation and Content conference (AODC) in Melbourne. On Friday, the third day of the conference, it was my turn to give a presentation.

My AODC presentation was about using a wiki for technical documentation. Here are the slides and supplementary material from my presentation:

• Slides with supplementary notes
• Slides only

I hope the slides with additional notes will be useful to the conference attendees, and maybe also to people who couldn’t make it to the conference this year.

Update November 2009: I wrote an article based on the presentation, which appears in the October 2009 edition of Southern Communicator. A PDF extract is available for download from this blog post.

Background to the presentation

Writing technical documentation on a wiki is what I do all day and what I’ve been doing for almost two years now. I’ve been a technical writer for more than ten years, using various tools and working in various businesses. I’ve enjoyed every authoring tool I’ve used, and wikis are no exception. There are difficult bits, of course. But there’s that satisfaction you get when you see your document displayed in an aesthetically pleasing and functionally useful way. Wikis do it differently, but the sense of delight is the same.

I’m a technical writer at Atlassian. We use Confluence wiki more or less “out of the box” to author, manage and publish our documentation. We don’t extend the wiki’s core functionality via plugins or other customisations (with a few exceptions). There are two reasons for this decision:

• Atlassian follows the principle of “eating your own dogfood”. That means that you use your own products, so that you can feel your customers’ pain. And their pleasure
• We make our documentation available as an XML download, so that other people can upload it as a wiki space on their own Confluence instances. If we used a number of plugins that are not a standard part of Confluence, then other people would not be able to use the documentation in this way unless they installed the same plugins.

So my presentation was about the features of the wiki that are especially useful in technical documentation, and the procedures you might put in place to work around the bits that the wiki doesn’t do for you. The main points I discussed are:

• How a wiki is useful in agile development.
• Workflow and tracking.
• How to put some structure into wiki documentation.
• Release management.
• Steering wiki development — how we as technical writers can let wiki developers and plugin developers know what features we’d like in a wiki.

The content is similar to the talk I gave at WritersUA in Seattle, except that the AODC presentation was double the length (an hour instead of half an hour). So I was able to add some extra information and do more live demonstrations.

Breaking news not included in the notes

The presentation mentions the Scroll Wiki Exporter, that converts wiki markup to DocBook. In the last week K15t Software have released version 1.0 of Scroll, their first production release. See the Scroll web site and my blog post.

AODC day 2 – Design of context-sensitive help

This week I’m attending the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. Today is the second day of the conference.

Here are some notes I took from the session on user-centred design of context-sensitive help, by Matthew Ellison. I hope these notes are useful to people who couldn’t be at the conference this year. The AODC organisers will also publish the session slides and supplementary material once the conference is over.

User-Centred Design of Context-Sensitive Help

With a laugh, Matthew introduced himself:

“I am the equivalent of Tony Self but with a funny accent and a better shirt.”

In this presentation, Matthew concentrated on the information design side of things, rather than the technical implementation of context-sensitive help (CSH). He gave us a definition of CSH: “Direct access to help that is focused on the user’s current needs.” In practice, he said, we tend to provide help based on where the user is in the UI.

What do we mean by “context”? The more we can tie it down, the better help we can provide. For example, we might be able to detect and respond to: The window/dialogue/tab the user is on; the control they’re trying to use; the zoom level or other settings; previous history, such as other screens visited; role; printer connectivity and so on.

Looking to provide user-centred help, let’s look at how users behave with respect to help:

• Most people don’t consult the help ahead of time.
• They’re usually busy with the task when they need help.
• They’ll only use help if they think it will give them useful information. So Matthew says they’re unlikely to click a little question mark, because it is not a convincing indicator of useful information.
• They want to be interrupted for as short a time as possible.

We also need to consider the questions a user may ask when confronted with a task or screen. For example: What is this screen for? What do I need to enter in this field? Matthew thinks it’s unlikely they want task information in a context-sensitive topic, because they’re already busy with the task.

Matthew has noticed that some software vendors are moving towards procedural rather than reference topics. (For example, see the CSH for MadCap Flare from versions 3 to 4.) Apparently this is in response to feedback from users. But Matthew thinks this may be a misdirection.

As a consequence, one mistake the Flare help makes is to pack all the reference information into the step in the task topic. So for example, there may be a single step that tells you to complete the options on a screen. This step will now be very long because it contains all the reference information about each option.

By the way, Matthew remarked that he is a great fan of MadCap help.

In the Captivate help, the help links are now labelled as “Learn more” with an information icon. Unfortunately the help topics are very long, especially for online help use.

So Matthew thinks the CSH topics should answer the questions: “What is this? What should I enter? Which should I select?” And the topics should be written specifically for CSH rather than linking only to documentation written for other purposes.

Now Matthew discussed IBM’s Task Support Clusters, designed by Michael Hughes. The idea is that most people who use their help are coming in via CSH. They press help within the application rather than coming in via search.

So IBM identified the locations in the application where help is needed, and then built a self-contained group of topics that support that particular task.

Start with a keystone concept topic (provides critical conceptual information), then provide related tasks and reference. The topics in a cluster are all interrelated by links pointing to each other, but there are no links that point outside the cluster. So the users cannot get lost by following links all over the help system.

The idea is that 80% of the time, the users will read the keystone concept topic and that will be enough. Don’t try to answer all questions in this topic, just the most likely questions users will have.

Now Matthew discussed contextual help. This is additional information that’s actually part of the application and supplements the UI. It’s more likely that people will read this, because they don’t have to open up the help.

This is inline help, available via popups or expanding/dropdown text, or just simply on the screen. This help must be well written, because there’s very little space. Recommended length is one to three short sentences for the entire page. But just one phrase or sentence for a single field.

For the help links, use the actual question the user may ask e.g. the link might say “What is a member name?” When you click it, you get a popup answering the question. Or “See some examples” might pop up some example values for a particular field.

MadCap Flare has this kind of popup help. They’re also working on the functionality that will allow us to put it into our own help systems when using Flare — currently only for DotNet applications.

Quick help or popups should link to full help system for deeper information. MadCap Flare is doing this in their new popup help.

SnagIt’s balloon help is great — it knows what you’ve just done and suggests what you might want to do next. After a while the balloons disappear, because it assumes you know how to do it now.

Also guided help may be a good way of providing procedural help. See Matthew’s presentation from last year’s AODC conference. The application guides you through your task and actually stops you from doing the wrong thing. SHO Guide is a very interesting product that allows you to do this.

Thank you for another great session, Matthew.