Linking to external blog posts from our documentation

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:

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

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

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.

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 25 July 2009, in atlassian, Confluence, Crowd, technical writing, trees, wiki and tagged , , , , , , , , , , , , . Bookmark the permalink. 5 Comments.

  1. Nice idea! And I loved the ‘tips’ diversion!!

  2. We’re in business🙂 We’ve published the “Tips of the Trade” pages for JIRA, Confluence, Bamboo and Crowd. I wrote a post on the Atlassian blog about it today. And we got our first offer from a blogger to write a post for JIRA. Awesome!

  3. Do you follow up to make sure the links remain alive? I have a personal problem with broken links (I’m getting professional help😉

    • LOL.

      That’s a good point, though. I’m going to add a note to our release procedures, to check the links on the page. It’s not that they’re related to a product release, but we need something to hook the link-check into.

      Thanks Richard🙂
      Sarah

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: