ffeathers — a technical writer’s blog

Do wikis save trees, and do we even want to save trees? Global warming, carbon-trading, green politics — where do wikis fit in, and are they even relevant?

I’ve worked in an office environment for quite a few years. Recently, I’ve started using a wiki to write, review, update and read documents and to share ideas. My desk is definitely more paper-free than ever before, largely due to the use of the wiki.

So my gut-feeling is to say, ‘Hey, wikis save trees!’ Being a tree-hugger and a wiki-hugger both, this feels like a good place to be.

But take a look at this article by Chris Anderson, which seems to prove that my good place is an illusion. Printed documents have a lower carbon footprint than online documents! So even if wikis save trees (which is debatable in itself) perhaps we don’t want to save trees. The paper industry puts them back in the ground, whereas a wiki doesn’t.

Chris Anderson’s article has a very long, heated and interesting comment trail. After reading it, I’d like to take a slightly different tack. He is concentrating on articles which are written once, and then read by many people. Websites are viewer-intensive.

How is a wiki different to a web page?

Many wikis are used for short-term collaboration rather than, or as well as, longer-term information storage. You might put an idea up on a wiki. A number of people would then review it, add their comments, and update the page. At the end of the process, an idea has been formed and is out there in the noosphere. People probably won’t go back to the wiki often to look at that particular idea. You could say the wiki is scribble-intensive.
The key thing is: In the review and refinement process, if we use a wiki then we aren’t passing around and scribbling on pieces of paper. We aren’t even exchanging long and confusing email chains which eventually force you to print them out just to keep track of who said what in reply to whom. Nor are we using Word documents, where the change-tracking is just as confusing Nor even any backs of envelopes or matchboxes.

Instead, the wiki page distills and merges all updates so that it shows the latest aggregation at any one time. And if you need to, you can go back and examine the change history to see who did what.

We’re online anyway. Given that the bad effects of the technology exist whether you use a wiki or some other form of website or computer technology, perhaps wikis are a step in the right direction.

What do you think?

Does anyone have any figures which go to prove this question either way? Maybe someone in the publishing industry has some experience of using a wiki for pre-publication drafting and review. Or perhaps there are some other industry-specific stories out there. Do you have anecdotal evidence, or even some documented statistics?

Ozzie tree shedding its bark

Here’s a tree in our garden. In early summer (that’s December on this side of the world, when I took this picture) the tree chucks all its bark on the ground. The new ’skin’ underneath is a lovely mixture of salmon pinks, oranges and greys.

The story goes that early visitors to Australia were amazed by trees like this, because they shed their bark in summer rather than their leaves in winter.

Sydney Red Gum (Angophora costata) aka smooth-barked apple.

Some words are captivating. Here are a few I’ve come across lately. They’re all related to linguistics. Maybe that’s why they appeal to me. Or maybe it’s just the way they sound. I’d be interested to know if you think these words are cute, and whether it’s because you’re a linguaphile too?

Bahuvrihi — a compound word like ‘lowlife’ or ’sabertooth’, where the meaning of the word is not a type defined by one of its parts. A ’sabertooth’ is a type of tiger, not a type of tooth. A ‘lowlife’ is a type of person, not a type of life. This property is significant, because it affects how we use the word in a sentence. For example, when talking about more than one of these things, we automatically use the regular plural rather than the irregular. So we say ‘I went back in time and saw a lot of sabertooths’ — not ’saberteeth’. And we say ‘lowlifes’, not ‘lowlives’. Compare ‘workman’ (not a bahuvrihi, because a workman is a type of man) with ‘walkman’ (a bahuvrihi). We talk about many ‘workmen’. Can we say, ‘how many walkmen do you have’?

Dvandva – a compound word made of two equally-weighted nouns, like ‘girlfriend’ and ’singer-songwriter’. These words have a similarly intriguing effect on our internal language generator, but let’s not go there

Synechdoche – that’s when you use part of something to refer to its whole. ‘I got me a new set of wheels’ means I bought a car, not just the wheels. When you ‘count heads’, you are counting the number of people, not just their heads.

And my favourite: hapax legomenon — a word or term which is used only once in a particular body of text.

This weekend I’ve been writing some Christmas cards, and struggling as usual to find the right words. Maybe I’ll drop in the odd hapax legomenon to spice things up

Thank you to Kate for lending me Words and Rules, the book in which I found these words. And to Steven Pinker for writing it.

Some tree news:

Here’s a tree recovering from a fire in the Manly Dam reserve:

And here’s a grass tree (Xanthorrhoea) which survived the fire altogether:

A wiki is a living organism. Its content is dynamic, continuously updated, commented on, subscribed to and watched by thousands of people all over the world. How does this work with technical documentation that is release-specific? Can you baseline your documentation? What if you are documenting a piece of software or some other product that goes through a regular release cycle, and your customers need to access the documentation which corresponds to their specific version of your product? This is elementary release management, bread and butter to technical writers. But can a wiki do it?

This week I created an archive space on our Confluence documentation wiki, in preparation for an upcoming major release of Atlassian Crowd. So now’s a good time to talk about the way we manage the technical documentation in correlation with our software releases. And to find out how other people are doing it.

Let’s say your wiki pages tell people how to use a toaster. And let’s say the very latest toaster in the product line, due out before Christmas, has a bright new quick-toast button. But there are thousands of customers out there who already have the original product and rely on it heavily - even without the shiny new button. What should your documents say about the button? Even more complicated: What if the toast-insertion mechanism is about to change from the old shove-it-in-by-hand method to a fancy new sliding widget?

There are a few strategies:

• Have separate documents for each version of the toaster.
• Have only one document, describe all features including the newest, and add a note that the quick-toast button is available only on the latest toasters. Also explain how the toast-insertion functionality has been enhanced. You could even hint that your customers should consider upgrading their toaster.
• Ignore older versions of the product, and only give instructions on using the very latest version.
• Any more? Let me know how you’ve done it.

Our choice:

We’ve chosen the first option. The second might result in a long list of notes, tracking a feature’s changes through the various releases of the product. This might become confusing in the long run. (But the second option does have its attractions - it’s a lot simpler, from the point of view of document management.)

We make use of ’spaces’. A space is a sort of wiki-within-a-wiki, and is part of a Confluence wiki. If your wiki doesn’t allow spaces, then you might consider having separate wiki instances for each software release.

Here’s how we do it:

• The ‘main’ documentation space always contains the documentation for the latest release of the software - such as Crowd.
• ‘Archive’ spaces contain the documentation for each previous major release of the software - such as Crowd 1.0.
• We also provide PDF, HTML and XML versions of the documentation - here they are for all the Crowd releases.

The fly in the ointment.

That sounds quite simple, huh. But as usual, there are some idiosyncrasies which need a bit of working around. The tricky bit is in the first bullet point above - the ‘main’ space always contains the documentation for the latest software release.

So we can’t start adding information about the new release until release date. And we can’t archive off the current space or create a new ‘draft’ space which will take its place at release date.

Why not? Two very important reasons:

1. Lots of people all over the world have hyperlinks into the documentation space, and subscribe to RSS feeds from it, and add ‘watches’ to pages on it, and comment on it. So we can’t archive the existing main space - that would break all their links and stuff.
2. The wiki is alive. As well as the technical writers, we have support staff and developers continuously updating the content. If we created a draft space and then later used it to replace the current space, we’d lose all updates made since the draft was created. And if we ‘froze’ the current space, the wiki wouldn’t be alive.

The fly catchers.

How do we solve the problem? Well, it takes a fair bit of organisation, and the help of a couple of tools.

When documenting new features for the upcoming release, we create pages in the wiki and ‘hide’ them from public view using Confluence’s page restriction functionality. And we make a note to ‘unhide’ the page on release date.

When we need to add or change existing pages due to changes in the upcoming release, we can’t make the change until release date. So we make detailed notes about the changes that need to be made.

Some time before release day, we make an archive copy which will become the documentation for the previous release (now still the current release).

On release day, we first update the space description so that it refers to the latest software release. Then we go through our ‘unhide’ and ‘update’ notes, applying the changes to the main space.

Where do we make the notes, you may ask? In a JIRA task, of course.

Summing it up:

Yes, a wiki can handle release-dependent documentation reliably and usefully. It’s pretty similar to using any other documentation system - find the tools that will help, and then make a plan to make them work to your requirements.

Wikis save trees.

Completely off topic but I wanted to add a pretty picture because release-management is a bit of a dry subject. Here’s a gum tree we came across this week, while walking through the Manly Dam parklands. The multi-coloured bark is a lovely sight, and quite common too. Does anyone know the name of this tree?

At university, I studied English with a strong emphasis on linguistics. This week a colleague at work, after reading my recent blog posts about language, let me know that she had studied linguistics too. So why are we both now in Information Technology (IT)? Also, John R made a thought-provoking comment. So now I’m following up on those two comments. And at the end, I’ll tell you how my trees are doing.

First of all, exactly why is this sentence funny or at least quirky: “Drive carefully when wet”?

Secondly, John R’s comment got me to thinking about how, with my fascination for linguistics, I ended up in IT. What makes a technical writer tick, and is the tick-mechanism anything like the widget that powers a systems engineer? Do John R (a self-professed ‘computationist’) and I (a linguaphile) actually share a habit of putting brackets around things and even indulging in the odd XOR?

Linguists have spent a lot of time trying to describe the knowledge common to speakers of a particular language. Without a shared knowledge, we wouldn’t be able to communicate. Some linguists think that there’s even an innate structural understanding shared by all humans, irrespective of which language they speak. So our brains come pre-wired with the “deep structural” rules of language, and we just have to plug in the specific language we need.

It seems fairly obvious that a language has a structure, and that all speakers of the language are able to manipulate the structure to produce unique, never-before spoken sentences with amazing ease. But describing the structure and its ability to generate new sentences has proved quite tricky.

Still, there’s hope. Take our sentence “Drive carefully when wet”. You might represent it like this:

Read the diagram starting from the top: A sentence (S) may consist of a noun phrase (NP) and a verb phrase (VP). A noun phrase may consist of a pronoun (Pro). A verb phrase may consist of a verb (V) plus an adverb (Adv) plus another sentence. And so on.

Linguists have also created a way to describe phrase-structure rules, complete with brackets and symbols to keep computationists happy. For example:

• S –> NP VP (A sentence may consist of a noun phrase and a verb phrase)
• NP –> Pro (A noun phrase may consist of a pronoun)
• And so on.

And then you can add other logistical provisions, like:

• “You” deletion: In an imperative sentence (i.e. a command), omit the “you”.
• Pronoun matching: The second pronoun, also missing in our sentence, is assumed to be the same as the first pronoun.

……So…… that’s why it’s funny. Get it?

The design of computer languages, and other artificial languages, owes much to the work of linguists. Chomsky, in particular, is an easy mark. He’s the man everyone loves to shoot down. But his work on the theory of a universal grammar, transformational-generative grammars, the Chomsky hierarchy and the Chomsky normal form set the basis for much of what we do today.

So that may be why my colleague and I, linguists both, found our way into IT.

I think there are probably two sorts (or more ) of people. Those like me, who seem to organise things into groups automatically (yeah, those brackets). The groupings are fluid and flexible, but the fact remains that we like them to be there. And then there are the people who float much more freely in their ecosystems: go with the flow, synchronicity rocks, hey man what’s the odd misplaced pronoun between friends?

Sometimes it amazes me how many different world views there are out there, just walking down the street next to me. And that we actually do manage to communicate with each other!

Moving on to my two trees:

Two months ago, I planted two trees. I promised a progress report every now and then. The trees are about the same age as this blog. And they’re doing great.

Here’s the paperbark, now 50cm high. (Was 40cm on 1 September.)

Here’s the old man banksia, now 32cm. (Was 17cm on 1 September.)

Atlassian, the company I work for, allows its staff members six days per year for volunteer work. You can choose where you donate your time, and still receive your usual salary. Impressive, huh.

My pet cause is conservation, and in particular bush regeneration. I spend a lot of time just in my own garden, hauling out nasties like agapanthus and asparagus fern and putting in native plants. A couple of days ago, my neighbour looked on in horror as I uprooted yet another hank of agapanthus. “Are you a greenie?” she asked. I started to say, “No”, then thought about it. I guess I am. Not a dyed-in-the-wool greenie. But becoming more and more convinced that we need to do something about climate change and the homogenisation of our environments.

So, today was my first “volunteering” day. Volunteering is a big thing in Australia. It’s part of the national culture. Try googling it, if you dare. The most well-known volunteers are the fire fighters. But there are lots of other opportunities. I chose Conservation Volunteers Australia (CVA). They go out in groups of ten to twelve people every day, and tackle a patch of bush that’s under pressure from non-indigenous plants or other threats.

Our group was interesting. There were three new people, including me. The others were all regulars. Some of them volunteer with CVA two or three days every week! One person had brought her daughter - at three years old, the youngest member of the team.

Above: The smallest, eager to get started.

One of the regulars is Anna (not her real name). It was Anna’s birthday, so the CVA team leader had baked her a cake complete with candles. We had it for morning tea. One of Anna’s birthday presents was a pair of gardening gloves. That’s dedication for you.

We targeted an area near the Curl Curl lagoon. A week before, people had been hard at work removing the noxious lantana. Here’s what the patch looked like when we started:

Above: Lantana massacre.

And here’s the spot I decided to make my own:

Above: My patch before I started.

Everyone got stuck in, pulling out the last remaining roots and preparing the ground:

Above: Hard at work.

Here are the plants we put in:

Above: Pigface (Carpobrotus). Info. Evidently this one grows fast and furious - a good ground cover for difficult terrain. We made sure we planted it in one particular area only.

Above: Porcupine grass (Spinifex). Info.

Above: Pelargonium. Info. This is a native variety of the popular pelargonium/geranium family.

Above: Hibbertia. Info. They say this one is quite hardy too, and makes very good ground cover.

And here’s my own little patch after a couple of hours’ work:

Above: My patch done.

It’s a good feeling at the end of the day, to have made some sort of difference in the world out there.

To remember for next time: Take some insect repellent!