ffeathers — a technical writer’s blog

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”

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?

For a technical writer, it can be difficult to find those use cases and examples that bring the documentation home to the reader. This is especially so in an agile environment, where requirement- and functional specifications tend to the minimalist. When you’re explaining an intangible and complex concept like “nested groups in Crowd”, it’s good to have some concrete examples that your reader can identify with.

This week, we released Crowd 1.4. Crowd is a web-based single sign-on (SSO) and identity management tool. That’s complex enough. Now add one of a new features in this release, the esoteric “nested group”.

“Nested group” — Is that a cluck of broody chooks?*

I’m quite proud of the new documentation on nested groups. It has some good use cases and diagrams.

* A “chook” is what we call a chicken in Australia

Where did the use cases come from?

Given that I’m working in an agile environment, where documentation is not abundant, and also that I don’t have face-to-face contact with our customers, it might have been difficult to find meaningful use cases. So where did they come from? Our customers “talk” to us via our Confluence wiki and our JIRA bug tracker, as well as other channels like user forums, support requests, etc. For a technical writer, the community wiki and bug tracker can be a good source of information about requirements and the stuff that happens to our customers out there in the wild.

For the nested groups documentation, I gleaned a lot of information from people’s comments on the feature request in JIRA. Thank you to those people who made such informed and informative comments! All I had to do was transform the information into more generic examples and add some illustrations.

Diagrams on a wiki?

I used Gliffy to create the diagrams. When I first tried Gliffy, I was amazed and delighted. I still am. Gliffy is a third-party plugin for Confluence, created by Gliffy Inc. My hat off to you guys.

What’s so magical about Gliffy and these diagrams? It’s that you can create and edit the diagram on the wiki page. When you view the diagram, it renders as a JPG on the web page. But if you have wiki permissions to edit the page, you can edit the diagram too. The Gliffy drawing interface is very intuitive to anyone who has used other drawing packages. This means that the drawings are “part” of the wiki — anyone can update them (permissions permitting) at any time, from any place.

Where do other technical writers get their examples?

I’d be really interested to hear where you glean your information from, especially if you’re in an agile environment or writing the documentation from scratch, with very little information falling down the traditional SDLC waterfall to land neatly in your pool of words.

We’re not business analysts, so we don’t have the time to do a full use case analysis or requirements investigation. But we often do need concrete and real examples. Has anyone else mined a bug tracker, walked a wiki or surfed a user forum to find this sort of information, and do you have any other handy tips?

An illustrated use case for this blog post?

A termite nest on a tree in Manly Dam Park (near Manly, NSW, Australia):