ffeathers — a technical writer’s blog

At work, we’ve just started a new set of documentation pages called “Tips of the Trade“. The project is still in the early stages. I thought other tech writers might be interested, so I’m blogging about it now. There will be a page for each of the products we document. The pages contain a set of links to useful blog posts written by people out there on the www. It’s a way of giving our readers more information and a way of involving external bloggers, developers and authors in our documentation.

Here are the first two:

• Crowd Tips of the Trade (Crowd is our SSO and user management application)
• Confluence Tips of the Trade (Confluence is our wiki)

The pages for JIRA bug tracker and Bamboo build manager are under review. We’ll be adding pages for our other products soon too.

Why have we started doing this?

The idea has been skulking around my head for a while, and it finally got dragged out into the open two weeks ago when, for the umpteenth time, someone asked me how we use wiki spaces to manage documentation versions. My answer was to point them to a blog post I’d written on this topic. But first I had to sift through the plethora of blog posts to find the ones about doing tech docs on wikis. And it’s not only me. Our technical sales and support guys have repeated the same search many times.

How much handier it would be if we could point the enquirer to a whole set of links about using wikis for technical documentation. Or even better, how awesome if people could just find the links for themselves in our documentation. Time saved, for them and for us. FTW.

Funnily enough, apart from tech docs on wikis, there are other things in life too. For example, haven’t you been dying to know how to secure a Grails application with Acegi and Crowd, or how to do SSO for RoundCube Webmail? Heh, the Crowd “Tips of the Trade” page has links to people who’ve done it.

Bringing the idea to life

So I put together two strawman pages, one for Confluence and one for Crowd. That was a fun and interesting exercise in itself. It took many hours. I had to search for the blog posts, then read each one and decide whether it suited the purpose. Because we’re talking about the technical documentation, I was looking specifically for “how to” guides rather than the broader use case materials.

Then I blogged about the idea and the strawmen on our extranet (a Confluence site that we use for company blog posts, planning, information management and so on). The response was immediate and enthusiastic.

That’s one of the things I love about working at Atlassian — all the feedback and support you get when you post an idea on the extranet. If you get no comments, then there’s a good chance the idea is a dud.

A rose by any other name

Isn’t it so often true that finding the name is the most difficult part of a new project? The page title started out as “Tips from the Trade”. But that wasn’t quite right. So for a short period of time we dubbed the pages “Tips from the Coalface”. Not ideal either. So now they’re “Tips of the Trade”. Better, but still not awesome.

The title doesn’t really resonate, scintillate, titillate

Any ideas?

The page layout

To categorise or not to categorise? I decided to go for “soft categorisation”. I don’t know if that term has ever been used before, but it kind of expresses what I mean.

Our human brains like to categorise things. It gives us a fuzzy sense of security and well being On a more mundane level, categories give a page a structure that is pleasing to the eye. They soften the “wall of text” effect. On the other hand, categories are fairly arbitrary or subjective and can hide valuable information.

So I put the blog posts into more-or-less meaningful categories, and put a box around each block of links with the category as title. But I didn’t mark the category as a heading. The result is that the table of contents at the top of the page does not show the categories. So you get the best of both worlds — a categorised and an uncategorised view of the world, uh, page.

For those who want to know the wiki markup:

• The table of contents at the top of the page is produced by a {toc} macro, showing only heading level 6: {toc:minLevel=6|maxLevel=6}
• The boxes are produced by the {panel} macro, with a choice of colours: {panel:title=Application Connectors
  |borderStyle=solid|borderColor=#ccc|titleBGColor=#6699cc
  |bgColor=#cee7ff}

Hint: You can see the wiki markup for yourself. Go to the Crowd Tips of the Trade, open the “Tools” menu and select “View Wiki Markup”.

I also decided not to put the posts into any particular order. I’m assuming that most people will find what they want via a search, so I’ve added some short descriptions of the content of each blog post.

Tips of an entirely different sort

Diversion alert!

This morning I had to trim the tips of my hair. Fully two inches off! But the cause of this tip-trimming is suitably romantic. My hair got hopelessly tangled when I flew in an open-cockpit Tiger Moth. Tip: If you ever get the chance to do something similar, tuck your hair under the helmet. It was a fantastic experience. Here are some pics and videos: Flying in a Tiger Moth.

A couple of months ago I radically pruned one of our bushes, because it was getting tall and a bit sparse in the middle. We were worried for a while that I’d been too enthusiastic. But now such pretty flowers have bloomed on all the blunt tips:

Linking to external blog posts from our documentation

My faith in gardening “how to” manuals is restored A close up view:

Linking to external blog posts from our documentation

What’s next for the “Tips of the Trade” project

When we have published more of the “Tips of the Trade” pages, I’ll write about them on the Atlassian blog. That way, our customers, community developers and community authors will know about them too. People will start stumbling across the pages via Google search and other searches, word of mouth, etc.

The documentation is on a wiki, so other Atlassians and contributors can add links to useful blog posts they come across. The tech writers monitor the wiki pages and will intervene if the links don’t quite suit the purpose of the document.

The pages provide useful information for our readers, especially about the edge cases and specific use cases that it’s so hard to cover in the core technical documentation. Thinking of the blog authors, they’ll probably like the fact that we’re linking to their posts. You scratch my back, I’ll scratch yours. That’s social, mate ®

I’m totally enjoying the work of compiling the pages and it will be interesting to see what feedback we get.

Recently I had the pleasure of working on some REST API documentation. I really enjoy this, because it is quite a change from the sort of thing I usually write. It’s highly technical stuff. The developers learned a lot while developing the code, and I learned a lot from working with them on the documentation.

Most of the documentation was written by our developers, in particular Sam Le Berrigaud. My job was to massage the style and structure and add bits on the periphery.

Some bloggers have commented that there’s a fair amount of information available on the web about REST principles, but not much about actual implementations. We have published our REST API design guidelines. We’ve also added a document explaining how to use our REST plugin module to create REST APIs, and another explaining how it works behind the scenes. There’s a glossary for those who, like me until a short while ago, know very little about REST.

When we release our first product that uses the REST module in the wild, I’ll be able to link to more documentation about REST implementations. That will probably be Crowd 2.0, which will provide a REST API based on the REST plugin. I’ll let you know when that happens, because then we’ll have some documentation on using the API itself.

This is exciting stuff, especially when you start getting an inkling of how neat and powerful a REST API can be. That’s why I enjoy writing about it. It’s satisfying and rewarding to write about technology that is neat and tidy.

So, the developers and I have learned a lot. But I’m sure there’s more to learn. We know that we need to add information on installing the REST plugin and its dependencies, and some examples along the lines of this forum discussion.

If you have written REST API documentation or designed and worked with REST APIs, I’d be really interested to hear your ideas, both about the API design and about the documentation itself. You can add comments to the documentation pages (it’s a wiki ) or to this blog post. In fact, if you are a contributor to the documentation, you can edit the wiki pages directly. I’ll pick up your updates and comments via my RSS feeds.

There’s nothing more RESTful than a tree

Here’s a picture of my Prickly Paperbark tree. How it’s grown! It is now one year nine months old, the same age as this blog. I planted the tree in August 2007 — see how small it was then.

Writing REST API documentation

Do you find it more difficult to put a document together when you’re not feeling all that motivated? I do. That’s because technical writing is a creative endeavour. You need a bit of flair to write those low-fat, high-fibre, not-entirely-sugar-free documents.

Some people may think technical writing is dry, boring and mundane. I don’t find that. It’s challenging and rewarding, and gets you in the zone as much as any other creative activity.

You need to engage the imaginative side of your brain to find the right words, to cut out the dross, and most importantly to put yourself in the place of your reader. Auto-generated documentation definitely has its place. But the best Javadoc includes some human-spawned words, clarifying the purpose and context of a class, method, etc.

After all, our readers are human, not machine. If machines did everything, there’d be no need for documentation. Or chocolate. Or anything.

Back to the trees

It’s a while since I’ve put a picture of a tree on my blog. What do trees have to do with documentation? Well, stretching for a connection: From time immemorial people have been writing on bark

I was out walking in the Ozzie bush this morning. Here’s an Old Man Banksia, being as picturesque and in-the-moment as they always are:

Is technical writing creative?

Here’s a gum tree in flower, with a rainbow lorikeet soaking up the zen:

Is technical writing creative?

Here’s the same tree, with Sydney city in the background and the lorikeet leaving:

Is technical writing creative?

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

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”