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.

A few months back, we started inviting external authors and developers to update our product documentation. We were a bit apprehensive. “Eek” was the technical term, I believe But the trial has been a great success and now it’s all systems go.

I blogged about the ins and outs in March. And I’ve just blogged about the results on the Atlassian blog.

So this is a short post, just to say “yaayyy”. And come join us if you like

Recently I’ve been drawing some diagrams in our technical documentation. This is a part of technical writing that I’ve always loved. Since our documentation is housed on a wiki, we have a couple of choices for creating diagrams. We could use a dedicated graphics program such as Visio, PowerPoint or SmartDraw, then convert the diagram into a JPEG, GIF or PNG image and upload it onto the wiki page. Or we can use Gliffy to draw directly on the wiki page. I think Gliffy is pretty magical, so I decided to blog about it here.

The need for diagrams seems to go in spurts. For a while all you need is words and screenshots. Then suddenly there’s a barrage of complex concepts, where a diagram works so much better than a web of words. I figure that if I start scribbling circles with connecting lines while getting the SME to explain a concept to me, then my readers will probably be grateful for a diagram too.

Why do I think Gliffy is magic?

We’re using Confluence wiki for our documentation. Gliffy is installed as a plugin on the Confluence server. What makes this magical is that anyone who has permission to update the wiki page can also update the diagram. There’s no need for extra software, just a web browser like Firefox or IE. Also, if I happen to be working from somewhere other than the office or my laptop, I’m not stuck without my drawing program. I can just log in to the wiki web site and scribble away.

Another reason for blogging about Gliffy right now is that I’ve just discovered two features in Gliffy that I didn’t know about before:

• You can include screenshots or other raster images into your diagram.
• You can hyperlink parts of the diagram. Gliffy will generate an image map for you.

Some examples in our documentation

When I realised that you can include a screenshot and make an image map (duh Sarah, that took a while) I tried it out by creating a diagram as an overview of a user guide. Here it is: Gadgets and Dashboards User Guide, still in beta but published to the whole wide world. Clicking the callouts will take you to the relevant section of the documentation.

Here’s a diagram that I created after getting the low down from an engineer on a complex subject. The diagram gives an overview of caching in Crowd, our user management and SSO product.

Gliffy as a drafting tool

Our Design team used the Crowd caching diagram, that I created in Gliffy, as a basis for a pretty picture to include in the Crowd 1.6 release notes.

The drawback (heh, no pun intended; spotted while proofreading) of the awesome picture in the release notes is that it would be time-consuming to edit and the Design team uses software that the technical writers don’t have. That’s OK for release notes because you don’t plan to update the diagram once the release notes have been published. But where there’s the possibility of ongoing maintenance, it’s safer and simpler to use a tool like Gliffy that supports editing the diagram as part of the wiki page.

What Gliffy looks like

Gliffy diagrams appear as JPEG images on the wiki page. If you have permission to update the wiki page, you’ll see an “Edit Diagram” link below the diagram. If you click the link, the Gliffy editing screen opens, looking like this:

Drawing diagrams on a wiki page

Here’s a thumbnail of a larger version of the same screenshot — click to expand it if the one above is difficult to read:

Drawing diagrams on a wiki page

As you can see, Gliffy looks very similar to the graphic tools we know and love. On the left are the different categories of shapes that you can drag onto your canvas. In the middle is the canvas you are working on. At the top and on the right are various tools and properties.

Tip: (This is the bit I didn’t realise until recently.) If you want to include an existing image into your Gliffy diagram, just upload that image (as a JPEG file) onto your Confluence page. It will appear in the list of images in the “Page Images” section on the left. Then you can drag it onto your Gliffy canvas.

Other wiki drawing and graphics tools

I don’t use any other wiki drawing tools at the moment, but I’ve had a look around because it’s interesting to see what is available.

For Confluence wiki:

• I’ve heard a lot of good things about Balsamiq Mockups. People use it at Atlassian, where I work, to create screen mockups and feature specifications.
• The Chart plugin displays various chart types and graphs, based on tables on the wiki page or attachments to the page. This is not a drawing tool, but it does display flowcharts and graphs based on editable content in the wiki page.
• The Confluence UML Sequence plugin lets you generate UML sequence diagrams using the free service at http://www.websequencediagrams.com/.
• The Graphviz plugin displays graphs based on Graph Visualization Software (Graphviz) and the DOT language. Again, this is not a drawing tool, but it does display flowcharts and graphs based on editable content in the wiki page.
• The Whiteboard plugin lets you insert a whiteboard onto your wiki page, so that you can write up your meeting notes in a sort of sticky or Post-it format.

I don’t know much about other wikis. A few searches yield the following:

• TikiWiki has a feature called Drawings that lets you create and edit drawings.
• MediaWiki has a number of promising diagram extensions.
• TWiki has the TWiki Draw plugin and the Chart plugin.
• I couldn’t find any information on drawing or diagram tools for PBworks, MindTouch Deki, Jive SBS (formerly Clearspace) or SocialText.

A BTW: When I was doing the above searches, it was often difficult to find the detail I needed because the web sites kept offering me videos and marketing blurb about how to use the wiki for various use cases and high-level feature overviews. My recommendation for all web site designers: Put a link to the technical documentation in a prominent place on all web site pages! Or include a search that encompasses the tech docs. Few people are as tenacious as I am when looking for a specific low-level feature requirement. Most will just go away after a couple of clicks.

Dear reader

If have you used any of the above tools for drawing diagrams on wiki pages, I’d love to know what you think of them. Do they do the job to the level that a technical writer requires, and do you know of other tools for drawing on a wiki page?