You’re writing a page on a wiki and you realise that some words you wrote just the other day would make sense here too. But where oh where are they? Or you want to include a picture, such as a logo, that’s used on other pages all over the show. Of course, you could just copy and paste. But can the wiki be more sophisticated than that?

I use the Confluence wiki for technical documentation. Some parts of this blog post are very specific to Confluence, because I thought other Confluence fans might find them useful.

For people who aren’t using Confluence, the first bit and the last bit of this blog post are for you The basic idea is that wikis (at least some of them) do allow content re-use. And the question at the end is, do you have any experience or hints about other wikis?

A quick note on terminology: In this blog post I’m using the words “content re-use” to mean the re-use of text or pages within the wiki itself. I’m not referring to single-sourcing of content across multiple media.

Why re-use content?

It saves time if you don’t have to keep re-inventing the word

Another problem with duplicated content is when something changes. You could easily miss some of the pages that need updating. So you run the risk of contradiction, incompleteness, and content which is just plain wrong.

If you want to translate your documentation into another language, it’s a great advantage to have as few words as possible. If you plan to engage someone else to do the translation for you, they will probably charge by word count or page count, so it could save you some $$ too.

Including content from other pages in Confluence

Confluence allows you to dynamically include content from one page into another page. You can include a whole page into another one, using the {include} macro. You can also define an ‘excerpt’ on a page, and then include that excerpted text into another page using the {excerpt-include} macro.

That’s old hat. We’ve been doing that for years So why am I writing about it?

Because we’ve started doing things a bit differently recently, and I thought other people might like to know about it.

At first, we did things like this:

• We defined an excerpt on the first page that happened to contain the wording we wanted. Then we included that wording into other pages as needed.
• Or we included an entire page from anywhere in the wiki into another page in the wiki.

There are a few disadvantages to doing it that way:

• When a whole page is included in another page, there’s no indication that the content is being re-used elsewhere. So anyone might change or even delete the page without realising they are affecting other pages.
• For both partial and whole includes, anyone might change a page name without realising that they are breaking the {excerpt-include} and {include} macros. (Confluence does not automatically fix changed page names in macros, only in links.)
• Re-used content is scattered throughout the wiki.

The better way

Now we’re using a set of pages called an “inclusions library”.

Here are some examples in our documentation:
Crowd Inclusions Library
Confluence Inclusions Library

Some notes about the inclusions libraries:

• The pages are located at the root of the wiki space, not under the “Home” page. This means that they will not appear in the table of contents on the left and they will not be picked up by the search in the left-hand navigation bar either.
• The pages will be picked up by other searches, because they are just normal wiki pages.
• For all new pages, we have decided to start the page name with an underscore e.g. “_My Page Name”. This indicates that the page is slightly unusual, and will help prevent people from changing the page name.

Including images from a central image repository in Confluence

You can attach your images to a single page and then include them into other pages. This means that the images are in one central place, instead of attached to an unknown number of pages. Here’s an example of an icon repository in our Atlassian IDE Plugin documentation.

What about you?

I did a very quick search to see what other wikis offer. The Socialtext documentation says you can include the contents of a page into another page. So does TWiki. That’s as far as I got.

I find this sort of feature offering really interesting because it shows that wiki creators are designing features for technical documentation and other formal writing, as much as the less structured collaboration use that is the wiki’s traditional comfort zone.

Have you used any content re-use features as part of the design of your documentation system, or are you using a wiki in this sort of structured way?

Re-use of a different kind

Here’s a ring-tailed possum making use of our telephone lines as a handy path from A to B.

Content re-use on a wiki

Content re-use on a wiki

Part of our job as technical writers is to give our readers a smooth ride through the text. And it’s not a small part of the job either. It’s important, even if it means we spend a fair bit of time correcting other people’s writing. Or does that just turn us into glorified copy editors — what do you think?

This isn’t new to most tech writers, but it came to mind again recently when I was making a couple of very small corrections to a page in our Confluence documentation. A reader had added a comment to the page, saying that she had noticed a couple of typos. Thank you Rosie (The comment is still on the page at time of writing this blog post, but it will probably disappear in a couple of weeks.)

Rosie had picked up two spelling mistakes: “serch” and “mutliple”. I myself find the second one particularly bothersome, because my eyes don’t quite believe that they’re seeing it right. So they go back a couple of times just to check that the mistake really is a mistake.

Why is this important?

Because we don’t want to distract our readers from the important stuff just because it’s written funny

OK, so prove it!

It’s easy enough when we’re talking about simple spelling mistakes. “Serch” should obviously be “search”. And “mutliple” is just painful. But what about the more complex aspects of grammar, vocabulary and style?

When you read a sentence like this:

Sarah is eat a chocolate.

you’re hit by a LAN.

And this one:

On the way to work this morning I saw a goldfish swimming around the bus.

gives you an N400 when you read the word “bus”.

A “LAN” (Left Anterior Negativity) is a measurable blip in the electrical impulse which your brain emits when your internal language processor encounters something ungrammatical — like the word “eat” in the first sentence. The blip takes between three and seven tenths of a second to register on an EEG.

An “N400″ blip happens when you encounter a word which doesn’t fit the context - like the word “bus” above. This one takes about four tenths of a second.

This information comes from Steven Pinker’s book, Words and Rules. It was pretty cool to learn that there’s a measurable physical manifestation of that feeling of discomfort I get when a sentence jars.

But what is “correct” English anyway?

I might suffer a LAN zap when you write “Remember to invite Peter and I to your party”. But many people don’t!

(BTW, “Peter and I” is wrong in that sentence, and I’m ready to battle that one out to the end if anyone’s game to take me on )

Or you might get a LAN buzz when I start a sentence with the word “or”. But I think it’s OK.

Why does the tech writer get to decide what’s right and what’s not?

We don’t. Language is a living, changing thing. Different words and constructs will sound good or bad to different people and at different times in history. Consistency is the key. Provided a document or a documentation suite is consistent in its usage of grammar, style and vocabulary, the reader will get that fabled smooth ride.

So which standards do we use? It doesn’t matter all that much, provided you pick a standard that is recognised in your neck of the woods.

At Atlassian, where I work, we use these two guides:

• Style manual for authors, editors and printers (John Wiley & Sons Australia)
• Macquarie Dictionary, Fourth Edition of the Essential Dictionary (University of Sydney)

We’re based in Australia. Our US office has copies of these books too, and we’ve agreed to go with the Australian standard because we’re originally an Ozzie company. I suspect that many Americans think it’s cute

Taking standardisation even further…

Scott from DMN writes about a DocTrain West session he attended, given by Berry Braster and listing the advantages of Simplified Technical English.

A Scribbly Gum tree in my garden

Moving on to scribbles and smoothness of another sort… The Scribbly Gum tree is quite common in this part of Australia. It has a lovely smooth white bark which gleams silver in the wet.

A smooth ride through the text

As you get closer, you notice some weird zigzag lines marring the smooth surface. It’s just as if someone has scribbled on the bark.

A smooth ride through the text

The markings can be quite intricate and almost seem have some meaning which you can’t quite discern.

A smooth ride through the text

But actually, the “drawings” are tunnels dug by the larvae of the Scribbly Bark moth, known less intimately as Ogmograptis scribula.

A smooth ride through the text

I vote that we make the Scribbly Gum the mascot of technical writers. All in favour say “aye”

Today I installed QEMU emulator and managed to get the OLPC XO’s Sugar user interface running on my Windows Vista laptop.

Sugar is based on Fedora with a custom GUI shell. Here’s Sugar over Vista:

Sugar offering to search for more “activities” i.e. XO applications:

It’s been an interesting experience There were a couple of hiccups. As soon as I’m sure of my facts, I’ll make my first update to the laptop.org wiki. So far, my only real problem is that I can’t install the QEMU accelerator module (Kqemu). Windows Vista says the .inf file “does not support this method of installation” But no worries,  I can do without the extra speed for now.

Next: Get to grips with Sugar in its emulated state.

Update: I found a Kqemu accelerator for Windows here: http://www.h7.dion.ne.jp/~qemu-win/
See “Accelerators” near bottom of page — link http://www.h6.dion.ne.jp/~kazuw/qemu-win/Kqemu-1.3.0pre11-install.exe
I installed it in folder “C:\Program Files\Qemu\Kqemu”. This seems to work — I don’t get the error message in the cmd window now.

I’ve just finished re-reading The Fountains of Paradise by Arthur C Clarke, published in 1979. A lot of people know him as SF-writer extraordinaire. Some would recognise his visionary engineering insights too. We might even acknowledge him as a pretty reasonable technical writer But did you know he was into Web 2.0 as well?

In The Fountains of Paradise, chapter 34 “Vertigo”, there are a by-the-way few paragraphs where the author explores the “development of global information systems” that might have occurred by the year 2142, when the book is set. He guesses there might be some automated solution for annoying tasks like sending birthday wishes to all your friends And then he goes on to say:

But the same technology that had eliminated one set of tasks had created even more demanding successors. Of these, perhaps the most important was the design of the Personal Interest Profile.

Most men updated their PIP on New Year’s Day, or their birthday. Morgan’s list contained fifty items; he had heard of people with hundreds. They must spend all their waking hours battling with the flood of information…

Hallo syndication, RSS and information overload. Alas, the ultimate engineer did not mention a solution to the problem. Perhaps we will have found one by 2142.

Fountains in Darling Harbour, Sydney:

Yesterday I attended the first techfest organised by OLPC Australia. It was a full day of talks, demonstrations and workshops aimed principally at people who might want to get involved on the technical side. I’ve come away with much more knowledge of the OLPC project itself as well as the hardware and software involved on the server and laptop sides.

The day was hosted by Pia Waugh and Jeff Waugh, with talks and workshops by Martin Langhoff and Joel Stanley. There were about 30 people, I’d guess. Most of the interest was in the technical side of things, but I did talk to a teacher who had travelled and worked in various African countries and is now working in Aboriginal Education in Sydney. For her, it was the educational aspects of the project and the instructional design of the hardware and software that are important.

In case anybody wants to know how you can get involved with the project, I’ve highlighted some bits in purple italics below.

Some terminology:

• OLPC — One Laptop Per Child. The OLPC project aims to give a specially-designed computer laptop, the XO, to children in remote and underprivileged areas of the world. The goal is to give these children access to the most up-to-date technologies for learning, experimentation, self-expression and collaboration.
• XO — the laptop provided to school children.
• XS — the server at the school.
• Sugar — the user interface i.e. the screen design, behaviour and tools which the XO presents to the children and other users.
• Activity — an XO application or program, such as Draw or Chat.

One of the breakout sessions at the end of the day:

e-Learning and challenges

The day’s first talk was an overview of e-learning and its challenges by Martin Langhoff. He covered the key factors arising from educational research, which drove the design of the XO and the thinking behind the OLPC project. We zigzagged between educational theory, anecdotes and technical specifications.

I didn’t get a good photo of Martin, but there’s one on the OLPC web site.

Here is some of the educational theory:

• Kids figure things out. Particularly when in small groups, where there’s a bit of competition, a lot of collaboration and the opportunity to teach others what you know. This happens better away from the classroom.
• Sugata Mitra’s Hole in the Wall project illustrates this concept. He made a hole in a wall which bounded a slum in India, where a number of children live and many do not attend school. On the other side of the wall, he placed a computer with internet access. The children could access the computer via keyboard and mouse. Within a couple of weeks, they were Googling for their favourite Bollywood starts. In a few more weeks, they were Googling in English.
• Constructionism is based on the discovery that we learn most when we are preparing material to present to others. This applies to small children too.
• The laptop’s user interface, Sugar, latches onto a child’s natural curiosity. It’s easy to get started, but the tools quick challenge the children by providing layers of complexity that are quite readily visible. For example, you can start developing a computer program with Turtle Art (a drag-and-drop way of moving chunks of code around) and then move into the Python programming language itself, via the XO’s “Pippy”. The names and terms line up with each other on each layer, so children quickly discover that a deeper layer is just a different and more flexible way of doing the same thing. Children start playing, and soon start giving adapted versions of the laptop’s inbuilt “activities” (applications or programs) to their friends. There’s more about the XO programming environment in my earlier blog post about OLPC in Sydney, and of course in the OLPC wiki.

Here are some of the environmental factors:

• The XO laptop is destined for remote areas, often with little or no power or connectivity. This demands non-conventional product development. For example, the laptop goes to sleep aggressively; avoids frequent polling, e.g. it doesn’t ask every 200 milliseconds what the battery status is ; and is able to deliver something useful even if there’s no or sporadic connectivity. There’s more about the XO hardware in my earlier blog post about OLPC in Sydney, and of course in the OLPC wiki.
• It would be useful for a school to have a way to request information from a website by URL, when the school does not have connectivity. Martin calls this “the return to waffle or UUCP”. The idea is that a messenger (someone who is travelling between the remote settlements and larger villages) would carry a USB stick with such requests. The messenger would go to the nearest point of internet connection and plug in the USB stick. A tool would crawl the requested websites and put the content on the stick, which the messenger would take back to the school server. This would also give the OLPC a chance to deliver patches and other updates to the school server.
• Interesting point: The XO has built-in hardware to act as a USB key. You’d just need to activate the software.

What about content — what information is or will be contained on the laptops and/or school servers? The project will be making a lot of use of Wikipedia. Here’s one place where people other than developers can help. They need good-quality content, principally in simple English or Spanish. Information about local culture is useful. Localisation of content to the small regional areas is very valuable.

Another way to contribute is to try out the new activities that developers are creating and give feedback. You can get a Sugar emulator. If you’re on Linux, they say that’s easy. Otherwise, you need to install vmware first.

Wiki slices

Martin mentioned this concept in his talk and I’ve put it in a section on its own because it’s so interesting.

The problem: There’s so much information out in the world. Even if you restrict yourself to Wikipedia (ignoring all debate about Wikipedia as a source of information), there’d still be a problem putting the whole of that single repository onto an XO laptop or an XS server. (More about the XS below.)

The OLPC has spearheaded the concept of a wiki slice as a way of delivering a cut-down set of information in a compressed format. The plan is to devise a set of scripts to select the appropriate information. For example, you might score the articles by popularity to decide what should be included in the cut-down information set. There’s a page on Wikipedia for the WikiProject Wikislice now too.

My thoughts: I work at Atlassian, which produces the Confluence wiki. At the moment, the wiki slice project is aimed at MediaWiki, which powers Wikipedia. I wonder how much work it would be to adapt the scripts to work on Confluence, or on other wikis? Also, we’re often asked about offline use of the wiki content. Could the wiki slice technology be useful outside OLPC?

“Unsupported legacy operating systems”

And the Microsoft Windows thing? According to Jeff Waugh, that’s just not relevant. Martin’s view was similar: The OLPC project is just forging ahead. The answer to doomsayers is along these lines:

We’ve done it. We are shipping laptops. Over 100 000 laptops are out there now, in the hands of children or being distributed.

At the moment, they’re working towards distributing 240 000 laptops in Peru, to between ten and fifteen thousand schools.

The OLPC project is not spending time on Windows integration. They’re also not stopping it. They have implemented a dual-boot option, which will be made available to those countries who want it. Windows will come on an SD card, at an extra cost of USD 10 ($3 for the operating system plus $7 for the card). If you boot with the card in, you’ll get Windows otherwise the XO will boot Linux. OLPC does not intend to prevent countries from loading Windows onto the laptops. Freedom of choice is integral to the world of open source.

What’s a pity is that the dual-boot feature will negatively impact the fast suspend/resume feature of the BIOS. The current version aggressively goes to sleep when not in use and resumes fast when needed.

Perhaps, when countries see that it doesn’t really work to use an unsupported legacy operating system, this will all blow over

OLPC Australia

In the second talk of the day, Jeff Waugh told us about the goals and status of OLPC in Australia. The goal is to support OLPC-related activities on this side of the planet. This will extend the reach of the project, because we are close to countries in Asia-Pacific region which need the XO and we are also close to people who are keen to contribute.

Jeff and Joel:

Areas of interest are:

• The Pacific
• Remote Australia
• Regional and metropolitan Australia.

OLPC Australia aims to build up a community of people who can contribute:

• Educators
• Technical people to deploy the laptops and servers
• Fund-raisers

Trials are being set up at the moment in metropolitan and regional schools, in Northern Territory and remoted Queensland, and in the Pacific. They are looking for volunteers to help set up the deployments. The work would be for a few weeks in one or two months’ time.

Jeff says that the project has had a good response from government. The current government aim is that “98% will have access to the National Broadband Network”. Geoff’s response is, “We are the other 2%. And we are an education project.”

Senator Kate Lundy took an XO to a Labor Party meeting. Kevin Rudd liked it. We know, because the XO took a photograph of his smile.

Jeff sees a huge opportunity in the Intervention project, and there are two state education departments interested.

OLPC Australia is looking for corporate sponsorships. As yet, there is no framework, but they are interested in any organisation which can give a concrete idea of how it can help.

OLPC Australia will also replace some of the content on the XO with Australia-focused information, such as the wiki slice content which deals with US presidents.

Live a life of XS - the school server

The third session was presented by Martin Langhoff covering the XS, or school server.

Until now, deployments have used standard server setups. Peru will be the first major deployment with the new XS which Martin is working on. At the moment, the focus is on infrastructure, backups of the XO laptops and configuration management tools. They also plan to look at security in more detail.

The physical design of the box caters for high temperatures. It will either hang, or rest on an integrated stand. The machine itself will take up one third of the space, the other two thirds will be just air flow. No fans.

Due to the unique nature of the project, a radically different administration model is needed. This is interesting to any system administrators out there. Martin is basing his ideas on models used at NASA, among others. Tools are based on the work of Steve Traugott and his infrastructures.org.

It’s a client-pull model, due to the problem of sporadic connectivity. The idea is that the servers keep track of which machines have managed to pull down the updates, so that the others can be manually updated via a USB stick.

There will be little or no end-user interface on the server. Initially, a technician will configure the server via auto-install. The server will be shipped to the school. With a bit of luck, someone at the school will plug it into a power socket. And that’s it.

Power supply may be sporadic. So the server needs to be able to roll back to a safe state if an update finished unexpectedly. Everything must just work. Martin calls this,

turning a complex server into an appliance.

What about passwords? How do we deal with the fact that a small team of technicians will be looking after thousands of machines? It’s not a good idea to have a master admin password that works for all time over all machines. The solution: At installation of the server, it will generate a list of one-time passwords which are unique to the server. This list will be stored at the network operations location. When the technician goes to a particular server, he will take a USB stick with ten or so of the passwords. This minimises the impact of a lost or publicised password.

On the collaboration side, Moodle is central to the server. MediaWiki is also used for asynchronous collaboration (as opposed to the synchronous collaboration supported by the XO laptop). The plan is to have several wiki slices running on the server, either independently or within MediaWiki.

Martin is also looking at content repositories. They need some way of sharing content among the schools. The content might be developed by teachers, an education department or even the children. The repository must be lightweight and distributed. It will support SCORM and IMS packages. World organisations such as WHO may even provide content this way.

Martin talked about the complexities of programming where you must look at long-term support, as opposed to regular updates being possible.

We can’t distribute emergency patches to the laptops or servers. After doing each bit of programming, we must consider all the important failure scenarios. This is very challenging.

A note also, that the laptops are independent of the servers. You can think of the server as an extesion of the laptops, providing backups, extra content, etc. When there are up to 20 or 30 laptops together, they communicate via the mesh networking — the “bunch of laptops under a tree”. When there are more laptops in the group, the server acts as a mesh portal, coordinating so that the network runs more efficiently.

Gung ho on the XO — the laptop

Joel Stanley gave the final talk of the day, before we broke up into groups to look at the machines themselves.

Joel ministering to an XO:

Joel gave a technical overview of the machine, starting with a look at its innards. We hopped from chip to chip, and a lot of it went over my head. Some snippets:

• You can now have mesh networking on your PC at home, by downloading the kernel module. It’s known to work on the B43 chips but they’re still ironing out problems with the Intel chip.
• The XO screen is trans-reflective i.e. it bounces incoming light off a mirror behind the screen to enhance the display. The next generation won’t need power at all to display the screen.
• The next generation of XO will support e-books like Amazon’s Kindle.
• The current software stack requires 256Meg of memory. This could be reduced, but that would take additional developer time.
• The XO includes a 1-gig hard drive.

The star of the day

XO closed:

Rotated screen:

eBook mode:

Side view, with a Samsung mobile phone:

Innards of the XO:

XO screen showing the Neighbourhood. Each little figure represents another XO or a shared activity:

XO screen showing the activities currently loaded. This one shows (going clockwise from the top) two instances of Turtle Art, Draw, the always-present activity at the bottom (I’ve forgotten what it’s called), two instances of Chat and the Distance activity:

XO screen showing the Distance activity. Two laptops can measure the distance between them by blurting sounds at each other:

My conclusion

The OLPC project is interesting on so many levels — technically there’s a lot of innovation and scope; but also politically, socially, economically and philosophically it’s one of those grand schemes that come along rarely.

When I first saw pictures of the XO laptop I was disappointed, because it looks a bit like one of those pretend-computers that you give to toddlers. It’s not. Those are toys. The functionality is limited to what is pre-programmed into the box. In contrast, the XO is a serious collaboration and learning tool which intrigues developers as much as children. In fact, it aims to rub out the line between the two.

Links to more information

• My earlier blog post about OLPC in Sydney
• OLPC Australia web site and blog
• OLPC project web site
• Documentation on the OLPC wiki

Last week I attended the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. I’ve posted a number of detailed reports on the sessions I attended. This post is a summary and a “thank you” to the organisers.

A big thank you to Penny Bradley, Tony Self and HyperWrite — you did an awesome job, with not a hitch to be seen! I learned a lot, met a lot of people and laughed a lot. It’s valuable to see what other technical writers are doing, because we all tend to work in a particular technology or field and can feel isolated from the bigger picture.

Best of all, I now know how to pronounce “DITA”. It’s “ditter”, or even “didder” and not “deeter”. This handy distinction avoids confusion of the XML standard with Dita Von Teese.

Summary of AODC posts

Here’s a list of my blog posts on the sessions I attended:

• AODC - DITA workshop
• AODC - trends, tools, technologies in online documentation
• AODC - a new grammar for online communication
• AODC - web technology and standards
• AODC - a DITA case study
• AODC - usability of embedded help
• AODC - reviewing a user interface
• AODC - authoring memory
• AODC - separating content, structure, format and behaviour
• AODC - guided help
• AODC - error messages

You can also get to the above posts via the AODC tag.

And here are some other interesting posts on and around the conference:

• A summary of AODC day 3 by Rhonda Bracey, one of the conference delegates — see her other posts on the AODC too, for excellent summaries and commentary.
• Tech writer’s spot — Elena Shebunyaeva comments on the “nu grammar”.
• Travelling Worm in Surfers Paradise — a review of the conference location from a hanger-on.

Next year?

I work at Atlassian. One of our products is a wiki called Confluence. Following the principle of eat your own dogfood, we do all our technical product documentation (well, almost all) on the Confluence wiki. For example:

• The Crowd documentation on our Confluence site.
• The Confluence documentation, also on the Confluence site.

At the AODC conference, a number of people were interested. What’s it like to do technical documentation on a wiki? What works well, what doesn’t? Why do we use Confluence for our documentation? Can customers contribute to the documentation? What process do we use to review changes made by people other than the technical writers? These were just some of the questions people asked me. Tony suggested that this would be a good topic for a session at next year’s conference. There’s certainly enough to talk about, and of course I find this topic exciting and absorbing

Pictures

Here are some snaps to make you wish you’d been there. First, the venue — Surfers Paradise on the Gold Coast, Queensland, Australia:

My name tag, fairly unadorned because I’m uninteresting i.e. this was my first AODC session and I come from a boring state in Oz:

A more interesting name tag:

If you are unfortunate enough to hail from New Zealand, you get a kiwi or a sheep (depending on the whim of the name-tag creator) instead of the Ozzie state. If you’ve attended a large number of sessions, you get the superman logo and are dubbed a super-veteran. I’m not sure what Marian did to get the no entry sign superimposed over her superman logo! The sun means something too, over and above the fact that it shines out from you and there are yet other pictures with meanings I’ve forgotten. Can anyone list the name-tag adornments?

This is a special edition of the ffeathers blog, to report the spectacular growth of my Prickly Paperbark tree since I last blogged about it approximately a month ago.

On 13 April, the tree was 172 cm. Today it’s 188 cm — grown 16 cm in five weeks! It’s now over 6 foot and taller than I am. I planted it in August last year, so it’s about nine months old.

Alas, it’s not only the Paperbark that has been growing. I spent a couple of hours this morning removing the Asthma Weed and Wandering Dew that had draped themselves all over the tree and its neighbourhood. Don’t gardens ever take a rest period in Sydney?

Just to reassure anyone who might be concerned about the Old Man Banksia I planted at the same time as the Paperbark: It’s doing fine too. It hasn’t grown so spectacularly since my last post a month ago, so it doesn’t warrant a special edition

Here’s a closeup of the trunk, with a peg for perspective:

This week I attended the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. The last session was entitled “The World’s Word Error Messages, or How to Scare End Users” presented by Frank “Choco” Munday.

Choco is a prolific and experienced technical writer, author and adventurer, and a member of the Australian Federal Police. He has collected a very amusing set of real-life error messages to illustrate and enliven the sound principles behind his talk — how to review and write good error messages.

The serious stuff

Software developers have to write text that is more important than any other text in the application or documentation: the labels etc on the UI and the error messages. It’s up to us, as technical writers, to review their work. Choco has “trained” his developers to consult him whenever they need to write something.

A good error message:

• Is polite and doesn’t blame the user.
• Clearly describes what’s wrong.
• Gives advice on how to fix it.
• Is in a human-readable language.
• Gives an indication of the severity of the problem.
• Does not include hostile words like “abort”, “kill”, “invalid”, “illegal”.
• Is targeted towards the user not the developer.

Some less-than-ideal error messages

All of these error messages are real i.e. they do or did appear in an operating system or application:

• “When casting from a number, the value must be a number less than infinity.”
• “Error: The operation completed successfully.”
• “Your mouse has moved. Windows must be restarted for the change to take effect.” This one is from the early days of the USB mouse in Windows 98 and now appears on t-shirts.
• “Value Error: insecure string pickle.” This comes from PaintShop Pro and has something to do with pickles in Python, the language used to create PaintShop Pro.
• “Please kill your PC!” From Nero.
• “Stop that!” From IE beta in early days of XML parser.
• “Press any key to continue or any other key to quit.” From Microsoft Exchange.
• “The command has been aborted. An internal error occured in Pro/DESKTOP. It is most likely that doing the same thing again will produce the same error.”

And lots more.

My conclusions

Choco, we are forever in your debt. This session was just perfect to for a Friday afternoon. Choco had us wiping away tears of laughter while getting the message (get it ) at the same time.

This week I attended the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. In one of Friday’s sessions, Matthew Ellison explained the concept of “guided help” and showed us some fascinating examples. His session was entitled “Guided Help: A Revolution for Software Help and Support?”

Matthew is a user-assistance professional who runs his own company, Matthew Ellison Consulting. He started his talk with sandy feet (The conference was in Surfers Paradise, three minutes’ walk from the beach.) He also started by admitting that the subject of “guided help”…

…gets me excited. I don’t usually say this about any subject. We Brits don’t, you know. I’d usually say I’m “moderately pleased”. But guided help gets me excited.

A definition of guided help

“Guided help” is help that leads someone through a task using the actual application, while:

• Highlighting the controls (buttons, fields, etc) that the learner should use.
• Displaying instructions in a caption or panel.
• Preventing the user from doing things that they shouldn’t.
• Giving the user the option to skip through some of the steps by having them done automatically.

“Guided help” is not a simulation, such as a Flash movie or e-learning session. Nor is it a wizard.

The key thing is that the user is actually completing a task within the application itself.

A by-the-way: This is not new. In 1986, Matthew worked with Digital’s ALL-IN-1 office automation suite and created training sessions which included the above features. Now, twenty years later, we’re talking about “guided help”.

Microsoft Guided Help

In the early days of Windows Vista, there was a neat, attractive and impressive guided help available if you were online at the time you requested help.

Technical writers take note: CNET said that this was one of their top 5 good things about Vista! Matthew asks:

How often does that happen to us? People are buying the product just to read the help

Alas, guided help is no longer available in Vista. Microsoft’s stated reason is that it caused too many maintenance headaches — each time Windows was updated, they needed to check the guided help topics too. (Welcome to our world ) Matthew thinks this is odd, because the guided help hooks into the accessibility support built into the application and does not include screenshots. It should be easier to update than conventional documents. Perhaps the reason was rather a security concern?

You can still get hold of some Microsoft guided help procedures in the Microsoft Knowledge Base. Matthew ran the procedure which leads you through the task of checking your disk drive for errors. It was neat, attractive and impressive. It greys out the windows which you’re not using and highlights the buttons you should click, with a text box and an arrow pointing to the relevant spot on your desktop. You can stop the procedure at any time. If you do something unexpected, it warns you and asks if you want to stop the help session.

Another caveat: The authoring tools are available only to Microsoft and the OEMs.

Gteko

Gteko has been purchased by Microsoft. Before the acquisition, Gteko produced a free, downloadable tool called PCPal. It’s still available (ignore the fact that it’s beta - it has been for a while ) but the latest version does not offer as much control nor as much information as the earlier versions. Matthew has the earlier version, of course

If you delve into the depths of HP Assistant and DELL Support, they too are based on Gteko technology.

When you run PCPal, it takes over your machine, clicks the buttons, opens the windows, etc. It even moves the active window to the centre of your screen. It tells you what it’s doing, and asks for your input when necessary. For example, if you ask it to set up a screen saver, it will by itself get as far as the Windows screen saver selection dialogue and then ask you to choose the one you want.

ActiveGuide from Rocket Software

ActiveGuide one is targeted at the EPSS (Electronic Performance Support Systems) market. You can use this tool with any web-based application. It includes an in-built authoring tool, ActiveGuide Studio. Matthew says that you don’t need to be a developer to create the guided help.

ActiveGuide uses client-side JavaScript to add a layer between the application and the user, overlaying the additional UI components on the original screens. It doesn’t touch the code on the server. The help topics are associated with the UI components via the IDs attached to the form elements etc, not to the x-y coordinates. So to some extent, the help is independent of the presentation and of small UI changes.

Try this online demo. It opens “Form 1099R 2003″. Now you can:

1. Click “ActiveGuide Coach” at top right, to see the guided help in action.
2. Click through the introductory text panels — do make sure you read them
3. At the first selection, choose “IRA” — it’s the only one that works in the demo.
4. At the second selection, choose “E-Z Pass” (the third option) — that’s the most fun!

eTracker from Solan Technologies

eTracker is the same sort of technology as ActiveGuide and works on desktop client applications as well as web applications. Again, programming skills are not necessary to build the guided help. Matthew was told that you can create a complex script in four hours.

My conclusions

Thank you Matthew, for a very interesting session with lots of useful examples. At Atlassian, where I work, we’ve been discussing the possiblity of adding guided help to some of our applications. One of our products is FishEye, which we acquired when the Cenqua guys joined Atlassian last year. Earlier versions of FishEye had a pretty neat guided help tour built into them.

I’m really keen on adding guided help to our products. In particular, this sort of technology can to some extent protect the documentation from UI changes, because the help text is hooked to the screen elements themselves and does not rely on screenshots or instructions like “Click the xxx link at top right of the screen”. Also, the help is right there, where the user needs it.

Plus, it’s just plain fun to do

This week I’m attending the Australasian Online Documentation and Content Conference (AODC) on the Gold Coast in Queensland, Australia. With his inimitable flair and style, Dave Gash presented a session this morning entitled “The Search for the UA Grail: True Separation of Content, Structure, Format and Behaviour”.

Dave is the owner of HyperTrain dot Com, specialising in training and consulting for hypertext developers. Today he told us what’s wrong with the way we traditionally do things, what’s wrong with the conventional wisdom on how we might improve our way of working, and what’s a better way.

What’s wrong with the traditional way we do things

The basic problem is that we write our content, e.g. a web page, and tweak elements of it on the fly. For example, we might make some text bold, or colour other text, or whatever. The result is spaghetti code — difficult to maintain and share.

What’s wrong with the conventional wisdom on improving the above situation

People usually say we should “separate format from content”. But what is “format”? That term is too vague. And the phrase implies that everything that’s not “content” is “format”. Wrong.

The better way

We should separate our document into four components instead of two:

• Content (which you might realise via XML)
• Structure (XSLT)
• Format (CSS)
• Behaviour (JavaScript)

What we’re aiming for:

• Maintainability — you can change one of the above four components without breaking the others.
• Re-usability — you can re-use the same bit of JavaScript, for example, in other documents.
• Separation of skill sets — different people can work on the component they know best and enjoy most.
• Simplified updating of content — content is likely to be the component you update most often.

How to do it

Dave demonstrated the procedure we would follow in order to separate a document into the above four components. There are five basic steps. Dave walked us through the details of each step, using code examples of CSS, JavaScript, XML and XSLT. In summary, the steps are:

1. Identify all JavaScript and move it to an external JS file.
2. Identify JavaScript that could be better done in CSS. Examples are “onmouseover” and “onmouseout” event handlers that change the style of the text item, and image swaps. Use the CSS “hover” pseudo-class instead.
   • Dave’s tip: You don’t have to specifically code the “I’m through hovering” handler because it’s implicit in the pseudo-class.
3. Move all CSS styles to an external file. Convert local formatting to classes too.

   Dave’s tip: If the boss says “Change the list spacing in all lists on all pages”, it’s in one spot — change it and take the rest of the day off.

4. Add semantic markup to the content, using XML.
5. Now it’s time for some XSLT. Identify the output HTML you want, then write the XSL transforms to produce it.
   • Write small, individual templates to create the HTML for each specific XML tag. Then use the “magic” <xsl:apply-templates/> element to pull it all together. This nests the processing of the templates, so that the transforms will just keep happening for each XML element, hierarchically down and back up the tree, until they’re all done.

The XSLT generates the HTML and links in the CSS and JavaScript.

Dave has made the code available on the “Downloads” tab of the HyperTrain dot Com web site.

A recommended editing tool: EditPlus.

Thank you for a great session, Dave. And a special thanks for changing “behavior” to “behaviour” throughout your presentation, just so that we Ozzies felt comfortable