A few months back, we started inviting external authors and developers to update our product documentation. We were a bit apprehensive. “Eek” was the technical term, I believe But the trial has been a great success and now it’s all systems go.

I blogged about the ins and outs in March. And I’ve just blogged about the results on the Atlassian blog.

So this is a short post, just to say “yaayyy”. And come join us if you like

Recently I’ve been drawing some diagrams in our technical documentation. This is a part of technical writing that I’ve always loved. Since our documentation is housed on a wiki, we have a couple of choices for creating diagrams. We could use a dedicated graphics program such as Visio, PowerPoint or SmartDraw, then convert the diagram into a JPEG, GIF or PNG image and upload it onto the wiki page. Or we can use Gliffy to draw directly on the wiki page. I think Gliffy is pretty magical, so I decided to blog about it here.

The need for diagrams seems to go in spurts. For a while all you need is words and screenshots. Then suddenly there’s a barrage of complex concepts, where a diagram works so much better than a web of words. I figure that if I start scribbling circles with connecting lines while getting the SME to explain a concept to me, then my readers will probably be grateful for a diagram too.

Why do I think Gliffy is magic?

We’re using Confluence wiki for our documentation. Gliffy is installed as a plugin on the Confluence server. What makes this magical is that anyone who has permission to update the wiki page can also update the diagram. There’s no need for extra software, just a web browser like Firefox or IE. Also, if I happen to be working from somewhere other than the office or my laptop, I’m not stuck without my drawing program. I can just log in to the wiki web site and scribble away.

Another reason for blogging about Gliffy right now is that I’ve just discovered two features in Gliffy that I didn’t know about before:

• You can include screenshots or other raster images into your diagram.
• You can hyperlink parts of the diagram. Gliffy will generate an image map for you.

Some examples in our documentation

When I realised that you can include a screenshot and make an image map (duh Sarah, that took a while) I tried it out by creating a diagram as an overview of a user guide. Here it is: Gadgets and Dashboards User Guide, still in beta but published to the whole wide world. Clicking the callouts will take you to the relevant section of the documentation.

Here’s a diagram that I created after getting the low down from an engineer on a complex subject. The diagram gives an overview of caching in Crowd, our user management and SSO product.

Gliffy as a drafting tool

Our Design team used the Crowd caching diagram, that I created in Gliffy, as a basis for a pretty picture to include in the Crowd 1.6 release notes.

The drawback (heh, no pun intended; spotted while proofreading) of the awesome picture in the release notes is that it would be time-consuming to edit and the Design team uses software that the technical writers don’t have. That’s OK for release notes because you don’t plan to update the diagram once the release notes have been published. But where there’s the possibility of ongoing maintenance, it’s safer and simpler to use a tool like Gliffy that supports editing the diagram as part of the wiki page.

What Gliffy looks like

Gliffy diagrams appear as JPEG images on the wiki page. If you have permission to update the wiki page, you’ll see an “Edit Diagram” link below the diagram. If you click the link, the Gliffy editing screen opens, looking like this:

Drawing diagrams on a wiki page

Here’s a thumbnail of a larger version of the same screenshot — click to expand it if the one above is difficult to read:

Drawing diagrams on a wiki page

As you can see, Gliffy looks very similar to the graphic tools we know and love. On the left are the different categories of shapes that you can drag onto your canvas. In the middle is the canvas you are working on. At the top and on the right are various tools and properties.

Tip: (This is the bit I didn’t realise until recently.) If you want to include an existing image into your Gliffy diagram, just upload that image (as a JPEG file) onto your Confluence page. It will appear in the list of images in the “Page Images” section on the left. Then you can drag it onto your Gliffy canvas.

Other wiki drawing and graphics tools

I don’t use any other wiki drawing tools at the moment, but I’ve had a look around because it’s interesting to see what is available.

For Confluence wiki:

• I’ve heard a lot of good things about Balsamiq Mockups. People use it at Atlassian, where I work, to create screen mockups and feature specifications.
• The Chart plugin displays various chart types and graphs, based on tables on the wiki page or attachments to the page. This is not a drawing tool, but it does display flowcharts and graphs based on editable content in the wiki page.
• The Confluence UML Sequence plugin lets you generate UML sequence diagrams using the free service at http://www.websequencediagrams.com/.
• The Graphviz plugin displays graphs based on Graph Visualization Software (Graphviz) and the DOT language. Again, this is not a drawing tool, but it does display flowcharts and graphs based on editable content in the wiki page.
• The Whiteboard plugin lets you insert a whiteboard onto your wiki page, so that you can write up your meeting notes in a sort of sticky or Post-it format.

I don’t know much about other wikis. A few searches yield the following:

• TikiWiki has a feature called Drawings that lets you create and edit drawings.
• MediaWiki has a number of promising diagram extensions.
• TWiki has the TWiki Draw plugin and the Chart plugin.
• I couldn’t find any information on drawing or diagram tools for PBworks, MindTouch Deki, Jive SBS (formerly Clearspace) or SocialText.

A BTW: When I was doing the above searches, it was often difficult to find the detail I needed because the web sites kept offering me videos and marketing blurb about how to use the wiki for various use cases and high-level feature overviews. My recommendation for all web site designers: Put a link to the technical documentation in a prominent place on all web site pages! Or include a search that encompasses the tech docs. Few people are as tenacious as I am when looking for a specific low-level feature requirement. Most will just go away after a couple of clicks.

Dear reader

If have you used any of the above tools for drawing diagrams on wiki pages, I’d love to know what you think of them. Do they do the job to the level that a technical writer requires, and do you know of other tools for drawing on a wiki page?

Scott Nesbitt has asked a number of technical writers, and I’m one of the privileged, if we’d like to write a guest post on the DMN Communications blog. So I did: What makes a technical writer tick?

Writing for someone else’s blog is fun! It’s also interesting.

What’s different

You suddenly have all sorts of new considerations. You don’t know exactly when your post will be published. Potentially, you don’t know your audience as well as when writing on your own blog. You’re not sure how much editing the blog owner will do on your post after you’ve submitted it. You don’t have hands-on control of the formatting and you can’t make final tweaks just before publication.

Publication date arrives

I waited with bated breath. Seeing my post appear: Fun — almost as if reading it for first time. Surprise — the format is unfamiliar. Even though I’ve visited DMN Communications often before, it was still odd to see my words up there in that format. When writing on your own blog, you write in a WYSIWYG editor. You craft the appearance along with the words.

Hmmm. That’s the way most of us operate in our day jobs too. This made me think again about the trend towards content reuse and single sourcing, such as via DITA, where you need to write format-agnostic content. It’s difficult!

From the point of view of the blog host

On the subject of inviting guests to blog on your site, Scott has written some interesting notes from his perspective.

Scott added some headings into my post. That was a good editorial decision. He also let me know that he had done it before he published the post. He added the image at the top, and then added my fish image at the bottom when I emailed it to him later. Awesome to-ing and fro-ing. Scott also let me know how much extra traffic my post had generated. That was cool. Thanks Scott!

Comments from readers

I’m thoroughly enjoying the comments other technical writers are leaving on the post. Who can resist the “fish called Rhonda“? Bring on the puns, guys and gals! And if you want to add more serious stuff, well, that’s OK too

Writing a guest blog post

Technical writers are simply the best. Better than all the rest. With another bow to Douglas Adams: It is a bizarrely improbable coincidence that anything so mind-bogglingly useful could have evolved purely by chance.

In the last couple of weeks, I’ve been trying an experiment — using Twitter as a medium for release notes. It’s been interesting, so I thought you’d like to read about it. We could use Twitter in other ways related to technical documentation too, such as hints and tips or FAQs. Let me know if you’ve done that already!

I’m going to start with a short introduction to Twitter, mentioning particularly the aspects that I found useful when tweeting release notes. If you’re already a twitterologist, you may want to skip that bit. Then I’ll describe how we’ve used Twitter as a method of communicating the highlights of our release notes.

An introduction to Twitter

Twitter is a service that allows you to send short messages to anyone who is interested in reading them. You can sign up for a free account at http://twitter.com. Then just type in your message where Twitter asks somewhat abruptly “What are you doing?” and click “Update”. Bob’s your uncle, you’ve tweeted.

Tweets

“Short” messages? Oh yes, very short, especially in technical writing terms The maximum length of each message, or tweet as they’re called, is 140 characters. There’s an art to saying something meaningful in such a short message. Especially when the message is a release note highlight. So be warned, you may spend quite a bit of time tailoring your tweet.

The tweet below illustrates a number of conventions tweeters use to make as much as possible of those 140 characters. I’ll tell you more about the conventions later, and how we can use some of them in our tweeted release notes.

Twitter as medium for release notes

Followers

According to some reports, there are approximately 10 million people using Twitter, and its growth rate is around 1,382 (more than a thousand) percent per year. (See Web Strategy blog.) That’s an awful lot of tweets to read. So what you do is “follow” people. Twitter will send you the tweets of the people that you are following. Similarly, other people will follow you so that they can read your tweets.

You can restrict the visibility of your tweets to only people you’ve allowed to see them. You can also block specific people from following you.

RT (retweet)

What I’ve found extremely interesting in Twitter is the conventions that have sprung up as people start using it for wider and more specific purposes. “Retweeting” is one of those conventions. If you like what someone said and want to spread the word while attributing the goodness to the original tweeter, you can “retweet” their message. Simply add the letters “RT” into your message, copy the original text, and tweet away. What’s more, there are Twitter clients that do this for you automatically. I’ve mentioned some clients later in this blog post.

In the tweet illustrated above, Alister Scott has retweeted one of my tweets. Thank you Alister

@ replies

When you want to reply to someone, or refer to them in such a way that they’ll know you’re doing it, include an “@” and the person’s Twitter username. For example, “@sarahmaddox”. Many clients provide a “reply” option that does this for you. Clients also have a separate column or tab showing the @ replies directed to you, so that they don’t get lost in the main stream of tweets.

#-tags and search

Another very useful convention is the #-tag. Let’s say you are sending a message about a particular subject, and you think other people would like to read and to send tweets about that subject on an ongoing basis. This may be for fun or for a more serious purpose. Just think up a keyword, prefix it with a “#”, and include it in your message.

In the tweet illustrated above, I used “#googlewave”.

Here are the realtime results for a Twitter search on “googlewave”. And here’s what people are saying right now about “funnywords”.

Other people will start using your keyword, and they will also search Twitter for other messages that contain the same keyword. Many Twitter clients will do the search for you. Twitter search returns results from all tweets sent by anyone in the whole wide world, not just the tweets sent by people you are following.

Combined with the #-tag, this makes a very interesting combination for our tweeted release notes.

Short URLs

A URL can be very long, consuming far too many of those valuable 140 characters. Luckily there are a few services on the web that will shorten your URL for you. The service gives you a short string that you can include in your tweet (or in an email, or a blog post, etc). When other people click the short string, they are bounced back to the service’s URL and then forwarded on to your original URL. Examples of such a service are TinyURL.com, bit.ly and tr.im.

In the tweet illustrated above, I used TinyURL.com.

Twitter clients

One of the most magical aspects of Twitter is that you don’t have to go to Twitter.com to use it. There are a number of Twitter clients that add useful functionality to your desktop and make it possible to tweet from your phone too.

The clients have built in extra functionality as the Twitter culture evolves:

• The use of a #-tag triggers an auto-link. If you click the link, it launches a Twitter search.
• The use of “@username”, e.g. “@sarahmaddox”, links to the user’s Twitter profile e.g. mine.
• Clients like TweetDeck provide sophisticated search functionality. You can define search criteria using AND, OR, quotes, etc and build a “permanent” search that notifies you whenever a new tweet arrives matching your criteria. The matching tweets can be from anyone, so they’re not restricted to your friends.
• Clients supply an easy way of shortening URLs. Some clients do it automatically, via a specific URL-shortening service like TinyURL.com, bit.ly or tr.im. Other clients offer you a range of services to choose from.

I have TweetDeck running on my Windows XP desktop and on my Windows Vista laptop. It’s built on Adobe Air and has a lot of useful features including a sophisticated search capability. Here’s what it looks like. In the left-hand column are some tweets from people I’m following. Next are replies sent to me (via “@sarahmaddox”). The two right-hand columns are specific searches I have set up. All this is configurable, including the order of the columns:

Twitter as medium for release notes

TweetDeck gives a handy notification when new tweets arrive from people you are following, or as replies to you, or that match your search criteria:

Twitter as a medium for release notes

Want to read and send tweets from your phone? Well, you can. On my iPhone, I have both Twitterific and TwitterFon. I prefer TwitterFon — see screenshot further down this blog post.

You can also send tweets to Twitter via SMS. That’s what I did before I got the iPhone. So at least you can tell people what you’re having for dinner, even if you can’t read what they’re having until you get back to your computer

Tweeting our release notes

So, how can we make use of all the above features and conventions to use Twitter as a medium for our release notes?

Aim

To emit a tweet per major highlighted point in the release notes, to include a link to the release notes and to provide a way for tweet consumers to see a collection of such related tweets.

A consideration

In general, people read only the last few minutes’ worth of tweets. It’s not like email, where people make an effort to at least scan their inbox when they’ve been out of touch for a few hours or days. We need to make sure our design catches as many people as possible, and shows them where to go for more information if they want it.

What we did

Here’s the plan of action:

• Use Atlassian’s corporate Twitter account, rather than a personal account. Release notes are in a weird place, partly technical documentation and partly marketing information. People follow Atlassian’s Twitter ID and know what to expect from it i.e. company news. So they’re not dismayed to receive marketing-type information.
• Use a #-tag to tie the tweets together. This is the most exciting bit. It provides a way for tweet consumers at any time to see a collection of such related tweets. A collection of release highlights is… the release notes. Ta da ♪ ♫
• Use a shortened URL (e.g. TinyURL.com, bit.ly or tr.im) to link to the release notes themselves, so that people can read the full details if they want to.
• Don’t send out all the tweets at once. This would spam people, and a number of other people would miss out on your news because they’re not reading their tweets at the time. Instead, send out two tweets a day, the second about four hours after the first, for two or three days.
• Try it out for three or four product releases, then assess feedback and decide whether to continue.

The results

So far, I’ve tweeted about two of our product releases: the Atlassian Eclipse Connector 1.0 and Confluence 3.0.

For the Eclipse Connector 1.0, I used a tag of “#EclipseConnector10″. (#-tags are not case sensitive, because the Twitter search is case agnostic.) Here’s a screenshot of the resulting search on the Twitter.com web UI, at a particular point in time:

Twitter as a medium for release notes

In the above screenshot, you can see the format we’re using for each tweet: the text of a highlight from the release notes, plus the #-tag (”#EclipseConnector10″) plus the short URL (”http://bit.ly/4mTLf”). Here’s the full content of one of the tweets:

Manage your Crucible code reviews via Eclipse Mylyn’s task-focused interface #EclipseConnector10 http://bit.ly/4mTLf

Of course, the search may or may not show something quite different if you click it now.

What’s interesting is that I tweeted using the Atlassian account (the tweets with the dark blue icon of a dude holding up  slice of the globe) and other people retweeted or just repeated the tweets. ‘Coz they liked them. Those are the entries with “RT” in the above screenshot.

For the Confluence 3.0 tweets, I used the tag “#Confluence30″. Here’s a screenshot of the resulting search on the Twitter.com web UI, at a particular point in time:

Twitter as a medium for release notes

And here’s a screenshot showing the resulting search via TwitterFon on the iPhone:

Twitter as a medium for release notes

And you can check what the search yields now.

Nothing can go wrong go wrong go wrong

Heh heh. Take a close look at the two screenshots above. One person “hijacked” our #Confluence30 tag to communicate a problem he had when upgrading to the new version of Confluence, and the workaround for the problem

Of course, it was totally foreseeable that people would tweet problems as well as praise, and would include “our” #-tag in their tweets. Nothing is sacred on Twitter. We decided it would be interesting to go ahead and see the sort of response we get. After all, people are saying all sorts of things about us all the time, on and off Twitter.

The iPhone screenshot above shows the same person’s problem tweet, plus another person who was letting people know about a particular feature in the Confluence release (Twitter-like status updates).

It’s been a fun and interesting experiment.

Other uses of Twitter

People are getting very creative with Twitter. Wikipedia lists some of the unusual situations where Twitter has proved useful.

As technical writers we can probably think up a gazillion ways to use Twitter. We could tweet hints and tips, or even FAQs if we’re super wordsmiths, using the #-tags and shortened URLs much as I’ve shown above. Have you tried this or anything similar?

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

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.

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.

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.

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.

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.

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 best practices for translation and localisation, by Emily Cotlier of Harris Stratex Networks. 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.

Translation and Localisation Best Practices

Emily started by asking how many of us work for companies that sell products in other countries, and how many of us know that our content needs translation. Most of the room said yes to both questions.

Some concepts:

• Translation = Translating from one language to another.
• Localisation = Aligning a product with the culture of a particular country. Some examples are the use of language, use of colour, spelling, use of sensitive images.
• Internationalisation = Designing a product so that it can be localised relatively easily.

Would a technical writer or technical communicator be qualified to manage a translation project? Emily says Yes. She listed the skills required to manage translation and localisation projects:

• Research
• Organisation of the source content
• Scheduling of the content release, along with the translated content
• Managing of freelancers
• Communication
• Global thinking

Next she gave some answers to the type of questions we have when considering such a project. Here are my notes, but please refer to Emily or other sources for up-to-date and regional information:

• How long does it take? Emily’s experience is that a document of 1000-3000 words requires 1 week turnaround; a short manual takes 2 weeks to a month; over 50 000 words takes one to two months, depending on length and on whether more than one translator is involved. Other factors are the inclusion of graphics, review/approval process, etc.
• How much does it cost? Recently, a complex manual cost USD 6500 (translator in China) and another cost USD 35000 (translator in USA).
• How do you manage the project? If you outsource the work, the pros are expertise and speed; the cons are a higher cost. If you do the work in-house, the pros are lower cost and retention of knowledge; the cons are the time required and the challenge.
• Who’s going to pay? Emily says be sure to sort this out beforehand, because the cost can be quite a surprise.

We took a look at what the localisation management technology can do. Examples of such tools are Trados, the localisation module in Author-IT, and many more. They provide an interface for translating. For example, they may lay the original content on one side and the translation on the other side. They compare source with the previously-translated version and indicate any differences, via highlighting on the interface for example. Good software will provide a translation memory. This means that it “remembers” what has been translated, offers existing translations for terms in the source, and points out what has changed since.

Preparing for content localisation:

• Use clear language. Avoid colloquialisms, passive statements and long convoluted sentences.
• Prepare a glossary that you can give to the translators, and use it as a style guide for the rest of the translation.
• Link to graphics rather than embedding them. They need to be translated via a graphics editor, not in the text translation tool. So remember to save them in editable format. Use numbers instead of text for callouts.

To keep your costs down, use single sourcing, and don’t send topics that haven’t changed and therefore don’t need translating again. Keep track of your files and graphics, so that you know what has changed.

Always assess whether extra translation costs are worth it. For example, you will need someone to do a native language review of the translated content. You may be able to ask someone in-house to do this, if there’s someone who speaks that language. Or you may have to outsource this work too.

On a software GUI and on labels in diagrams, be aware that the translation can often take up extra space on the GUI or diagram.

When working with translators/localisers recommended by other people, do your research to see the work they’ve done and any other references. Check the software they use to make sure it’s compatible with yours. Also ask them if they use translation memory software. Many don’t, and this can increase your costs dramatically.

A question from the floor: Who owns the translation memory?

Emily’s answer: We always make sure we get the translation memory back. This helps if you have to start using a different translator. Most translation tools can read each other’s format.

Once you’ve chosen your translator, share knowledge with them. Bring them on board, so that they can produce quality work. Spend time with them reviewing the materials and setting the expectations.

Appoint a person in your company to be the liaison person between you and the localiser, especially if you want to build a long-term relationship with them.

Tools for localising a software GUI (as opposed to documentation): Passolo; WizArt.

Remember that you need to relate the documentation to the GUI, where one or both may have been localised. So your documentation, when translated, may still need to refer to the untranslated GUI terms if the GUI has not been translated.

Managing the completed localised files: Your computer needs the international fonts/languages used in the translated content. Your online help generator must be able to handle the new language too. You also need a good archive system, to keep track of the duplicate sets of files you will now have, one for each language.

Emily also gave us very useful tips about the administrative side of things e.g. keeping a job log and keeping track of the text on images for translation.

Question time produced some interesting questions and comments:

1) Are audio translations similar to document translations?

Answer: You would translate from the scripts. This is usually relatively cheap because they tend to be simple. Then there would be an additional cost if you want to record the voice audio or add subtitles to a video.

2) A hint about translating images: Export them in SVG format. That’s very easy to translate because it’s just XML. Then convert them back to raster or whatever is required for your documentation.

A great presentation, Emily!