ffeathers — a technical writer’s blog

In August last year, I planted two trees at about the same time as I started this blog. Now the trees and this blog are just over a year old. A good opportunity for some stats

ffeathers

WordPress says that ffeathers has:

• 62 posts
• 184 comments
• 184 tags (hmm, interesting but meaningless coincidence)
• 17,216 total views
• 7,584 blocked spam comments (thank you Akismet)

The most popular post is The agile technical writer with 1,247 views.

Today, someone found ffeathers by Googling for:

“your mouse has moved” error

I hope you found what you were looking for

Prickly Paperbark

Yesterday, another person came here searching for:

paperbark tree information on growth

So in your honour, here’s some idea of what a Paperbark tree does in a year.

The Prickly Paperbark was a tube, about 40cm high, when I planted it in August last year. Now it’s nearly 2 metres high and quite robust. (It needs to be robust, to survive the onslaught of weeds, floods, cold and heat that our garden inflicts upon it.)

Prickly Paperbark a year ago, at 40cm

Prickly Paperbark now, at 198cm

It has a very pretty trunk and bark already. The diameter of the trunk is almost 3cm at its thickest part.

Prickly Paperbark close-up

Old Man Banksia

The Banksia has not grown much since I last measured it in April this year. It’s approximately one metre tall, and battling an ever-changing environment. Since I planted it, a couple of tree ferns have muscled in on the territory.

Old Man Banksia last year, at 17cm

Old Man Banksia now, at approx 1 metre

Still, it is putting up a gallant fight. Its trunk is almost 2cm in diameter and it always has a lot of new growth, although much of it goes sideways in an attempt to find the sun.

Old Man Banksia close-up

As well as my two favourites, we planted around 20 native trees and shrubs last year. Spring has sprung, and we’ll be shopping for more soon. Death to all agapanthus

Today I did my second stint with Conservation Volunteers Australia (CVA), pulling up noxious weeds and planting native plants in the Australian bush.

Atlassian, the company I work for, allows us five days a year of special leave, to work for a non-profit cause of our choice. We can do all five days in a block, or a day at a time, or even half a day at a time. The cause I feel passionately about is the environment and biodiversity. So I’ve decided to do a day’s work with the CVA every now and then.

And hard work it is too. The main aim is to pull out the non-native intruders and help the natural bush to re-establish itself.

The CVA team meets the volunteers in Sydney, and drives them and the equipment out to the day’s location. There we meet up with someone from the local council, and the day’s work is planned.

Getting to the root of the problem

Today we were in Sydney’s Northen Beaches, clearing a section of the bank along Manly Creek. Here are two of the biggest invaders we encountered:

Getting to the root of the problem

Above: Arrowhead Vine, also known as Turkey Rhubarb — Acetosa sagittata.

Getting to the root of the problem

Above: They did tell me the name of this one, but I’ve forgotten. That’s ironic, because this is the plant I spent most of the day with It has a long stem which travels along the ground, winding under the grass and other plants, and sticking up a cluster of leaves every now and then. It’s quite a satisfying plant to uproot.

It’s a great feeling, getting to the root of a problem

The last time I volunteered with CVA was ten months ago, in October last year. I wrote a blog about it then too. Today, it was a pleasant surprise to meet up with a couple of the same people! There were 14 of us today.

Getting to the root of the problem

A weird flashback happened when we spread a large sheet of heavy black plastic over the freshly-weeded earth, to stop the weeds growing back. Through my mind flashed the thought, “Where I come from, that sheet would be someone’s roof by tomorrow morning.” (I’m from Cape Town in South Africa. Nothing as useful as that sheet of plastic would remain unclaimed for very long.)

Getting to the root of the problem

What did I enjoy about today?

• Learning more about what’s a weed and what’s not.
• Winter sunshine.
• Birds — galahs, rainbow lorikeets, eastern rosellas and kookaburras.
• Not a wiki or a document in sight
• Fourteen people of different shapes, sizes and persuasions.
• Doing something that really matters. In the big scheme of things, as my mother would say.

It’s really a great aspect of working at Atlassian, that they give us the opportunity to use part of our working hours to do something like this. We spend so much of our lives at work, it’s hard sometimes to find a balance with family life and responsibilities. It’s even harder to find the time for something like this. Thanks guys!

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?