A blitz test of the documentation

This week at Atlassian we held a blitz test of the documentation that we were soon to publish with an upcoming software release. It was fun and productive. We made some nice improvements in the documentation. As a bonus, we found a cute bug in the application itself when we tested the procedure against the step-by-step guide.

Our QA team first introduced blitz tests, to test the applications themselves rather than the documentation. We decided to try it out on the documentation too.

What is a blitz test?

The doughty blitz testers

In a blitz test, people from all walks of life spend an hour doing concerted and concentrated testing of specific aspects of the product. It’s a way of timeboxing the testing. It’s also a way of viewing the product as whole rather than the disparate bits that have previously been reviewed individually. Best of all, it’s a way of working together on improving the product.

To say “people from all walks of life” is a bit of an exaggeration, of course. The point is that the developers, technical writers, product managers and various other people join the QA team and that we all work together for that hour on testing the product due for imminent release.

As technical writers, our product is the documentation. For this blitz test, we targeted the documentation for the release of Atlassian Crowd 2.1.

Preparing for the blitz test

First I contacted the development team leader and product manager to check whether they liked the idea of the team taking part in a documentation blitz test. They were enthusiastic. The Crowd team are great.

The next step was to create a test plan that everyone could work off, with the following information:

• Date and time of the blitz test.
• Names of the testers.
• Location. We held a kickoff meeting in the team area and then the testers worked at their own desks.
• Aim and scope of the blitz test.
• A list of all the new and updated documents that I wanted tested, grouped by functional area in the application.
• The test environment. In our case, we were testing the draft documentation on our production documentation wiki.
• Where and how people could record their test results and feedback.

At the appointed date and time, we all gathered in the area around the development team’s desks to confirm that everyone knew the areas of the application and the documents to be tested. We allocated one or more areas and documents to each person, and checked that everyone knew where to put their results and which chat room to join.

It’s on! People rushed back to their desks, the room took on an air of frenzied quiet, and the chat room and wiki exploded into action.

How did the testers provide their test results?

We offered various ways that people could record their results:

• Edit the documentation pages directly. The documentation is on a wiki, so that was easy.
• Add comments to the documentation pages. The pages were in draft status, so the content and the comments were visible to Atlassians only.
• Chat about the test findings in the team’s online chat room.
• Ping me on IM.
• Add a child page to the test plan on the internal wiki, documenting the test findings there.
• Add a comment to the test plan on the internal wiki.

The results

The development team were positive and enthusiastic about the experience and jumped in with a will.

• The development team leader suggested a few small additions to the more technical documents, clarifying the impact of changes and new features.
• A developer pointed out a page where the terminology used on the screens had changed again after I’d updated the documentation. We needed new screenshots and a change to a page name. Phew, that was a biggie.
• Other developers pointed out a number of small clarifications.
• Someone pointed out a change in behaviour that was actually a bug. Nothing major, just that the “Continue” button in one of the wizards no longer worked in the same way. You now need to click a tab instead of a “Continue” button when you want to move to the next stage. I’ve updated the documentation and we’ll fix the bug in the next release. At which stage I’ll change the documentation back again.
• Someone else found an issue that he’d fixed in the code, but had forgotten to mark as “fixed” in the issue tracker. The result was that I hadn’t updated the documentation, of course. This was a fairly big find too. Phew again.

Some feedback came directly to me via IM. What a good thing that you can copy and paste from an IM conversation!

Did anyone update the documentation itself? Yes indeedy! The product manager tweaked the release notes, and noted that he would produce some performance stats to illustrate a point.

What did the developers think of the documentation blitz test?

The Crowd team's standup toy at rest in the clasp of a monkey

After the blitz test was over, I asked the development team what they thought of the experiment. Here’s their feedback about why they thought it was beneficial:

• Team ownership of the documentation.
• Team building.
• The obvious verification that what we’ve specified in the docs is correct.
• It can be worthwhile double-checking the docs in case functionality or edge cases are missed in the docs (because we may have subtly changed the implementation without notifying the tech writers).

Was the blitz test a Good Thing?

From my point of view as technical writer, it was very valuable.

The development team and product manager had already reviewed the documentation piece by piece, as I developed it. The blitz test gave them the opportunity of viewing it as a whole.

People continued updating the documentation the day after the blitz. We released the software and published the documentation two days after the blitz test. We’re on a roll!

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:

• 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.

Gadgets, widgets, wikis, what next?

I’ve been experimenting with Google Gadgets and learning about OpenSocial. There’s a lot to learn still, but I do now have a gadget all of my own. Why am I looking at gadgets and why am I writing about them here?

For fun of course. But on top of that…

Why gadgets?

At Atlassian, where I work, we’re looking into gadgets in a big way and we’re using part of the OpenSocial specification for data exchange. We’re planning to update the dashboards for the Atlassian applications (like JIRA bug tracker, Confluence wiki, Crowd user management, etc) so that people have more control over their own dashboards. The idea is that you will be able to add bits of information from your JIRA site into your Confluence dashboard or page, or plug bits of Bamboo into JIRA, or whatever. So your dashboard can become more of a one-stop-shop for all your task-related information. To a certain extent you can do that already, using various plugins. But it would be nice to have a more standard way of adding, moving and removing the bits and pieces.

Kind of, “Drag me, drop me, x me. Well look at me, I’m coming back again… I’m still standing yeah yeah yeah.” Thank you Elton

Also, it will be frostily cool to use a more widely recognised standard, like OpenSocial and Google Gadgets, so that other people can build gadgets and use the Atlassian applications in weird and wonderful ways that we haven’t ourselves thought of. Once we’ve solved a few security considerations, people may even be able to embed gadgets from other web applications into the dashboards of their Atlassian applications.

Why write about gadgets here?

Every new feature needs documenting, and gadgets look like becoming a new feature in our products. Yee-hah! So I have an excuse to play around with gadgets and get to know what’s already out there. Then I’ll be able to document what we’re adding to the mix.

My gadget

My gadget is quite basic at the moment. It displays an RSS feed from WordPress.com, showing recent posts with the tag “technical-writing”. Of course!

The gadget allows you to set the background colour. It will greet you by name, once you’ve given it your name. And it knows whether it should say “Good morning”, “good afternoon” or “good evening”. I’ve used Feed2JS to provide the server-side parsing and formatting of the RSS feed. That’s about it for now. I plan to expand the gadget into the OpenSocial side of things as I learn.

I’ve installed my gadget on my iGoogle page and on my profile page at The Content Wrangler Community, which is hosted by Ning. Ning supports OpenSocial, as do quite a few other sites and applications. Here’s a list of OpenSocial containers.

Want to try it?

For the brave of heart, and with lots of caveats and disclaimers, here’s the URL for my gadget. This is the URL to use when adding the gadget to iGoogle or another website which supports gadgets.

If you install it on your iGoogle page, it should allow you to set the background colour and tell it your name. On The Content Wranger Community, the gadget displays but it does not allow me to enter my name or background colour.

If you’re mind-bogglingly fearless, you could try my gadget on one of the other containers and let me know what happens

What about other types of gadgets and widgets?

It’s exciting stuff. There are a few places on the web where you can build a gadget and then embed it into your web page.

In fact, if you build a widget at Widgetbox you can embed it onto a Confluence wiki page using the latest version of the Confluence Widget Connector. But that’s another story.

Some hints from my ventures into Google Gadgets

Here’s a screenshot of my iGoogle sandbox with the iGoogle menu on the left, then gadget’s output and my list of gadgets in the middle, and the gadgets editor on the right:

Gadgets, widgets, wikis, what next?

If you decide to play around with developing your own Google Gadgets, you may find these notes useful. They’re a product of much trial and error

• There are two Google Gadgets developer guides, one for the earlier “legacy” version of the gadget API and one for the new version which supports OpenSocial. Make sure you find the new one, if that’s what you want.
  
• Here’s the guide for the iGoogle sandbox, a development environment provided by Google where you can develop gadgets for iGoogle.
  
• To sign up for the sandbox, you need a Gmail account. Then go to this URL: http://www.google.com/ig/sandbox. Sign up using your Gmail email address. But here’s the catch: if you go to the above URL again, you will be signed out of the sandbox! Then you will need to sign up again at the same URL. No worries, just give the same information again, and you will get your sandbox access back with all your gadgets intact.
  
• You’ll know you are in the sandbox when the following words appear near the top left of your iGoogle page: “Welcome to the iGoogle Developer sandbox“.
• I didn’t realise that my iGoogle sandbox would appear as a new tab on my iGoogle page, so it took me a while to find it. After signing up, just examine your iGoogle page to see what has magically appeared on it!
• Another thing I didn’t realise is that the editor in which you create the gadgets is actually a gadget itself. So to use it, you need to add it to your iGoogle page (i.e. in the sandbox) in the same way as you would add any other gadget.  For some reason, it is not auto-added to your sandbox even though a number of other gadgets do automatically appear there. Your first experience of the editor is just as a text box in the middle of the developer’s guide, here. But you don’t have to keep going back to that page to edit your gadgets
• In your iGoogle sandbox, you’ll have a list of gadgets displayed in another gadget, called “My Gadgets”. This is where you add gadgets to your sandbox. For the gadgets you are busy developing, it’s a good idea to uncheck the “Cached” checkbox  in the “My Gadgets” list, so that you can see the results of your changes immediately.
• When you create a new gadget and save it in the editor, copy the new URL immediately (it’s at the top right of the editor box) and add the gadget to the “My Gadgets” list then and there. Otherwise you may have difficulty finding your gadget again.
• Save your gadget code somewhere else e.g. on your own machine using a text editor like Notebook. My Google gadgets editor did some odd things more than once, especially when I was copying code from one gadget to another.
• If your gadget doesn’t display the output you are expecting, look for the basic misplaced bracket or whatever, rather than assuming it’s some weird gadgety thingy that is causing the problem. I spent ages trying to figure out what I was misunderstanding, then eventually tracked the problem down to a missing curly bracket.
  
• Going going going gadgets
  

Finding use cases for Crowd nested groups documentation

For a technical writer, it can be difficult to find those use cases and examples that bring the documentation home to the reader. This is especially so in an agile environment, where requirement- and functional specifications tend to the minimalist. When you’re explaining an intangible and complex concept like “nested groups in Crowd”, it’s good to have some concrete examples that your reader can identify with.

This week, we released Crowd 1.4. Crowd is a web-based single sign-on (SSO) and identity management tool. That’s complex enough. Now add one of a new features in this release, the esoteric “nested group”.

“Nested group” — Is that a cluck of broody chooks?*

I’m quite proud of the new documentation on nested groups. It has some good use cases and diagrams.

* A “chook” is what we call a chicken in Australia

Where did the use cases come from?

Given that I’m working in an agile environment, where documentation is not abundant, and also that I don’t have face-to-face contact with our customers, it might have been difficult to find meaningful use cases. So where did they come from? Our customers “talk” to us via our Confluence wiki and our JIRA bug tracker, as well as other channels like user forums, support requests, etc. For a technical writer, the community wiki and bug tracker can be a good source of information about requirements and the stuff that happens to our customers out there in the wild.

For the nested groups documentation, I gleaned a lot of information from people’s comments on the feature request in JIRA. Thank you to those people who made such informed and informative comments! All I had to do was transform the information into more generic examples and add some illustrations.

Diagrams on a wiki?

I used Gliffy to create the diagrams. When I first tried Gliffy, I was amazed and delighted. I still am. Gliffy is a third-party plugin for Confluence, created by Gliffy Inc. My hat off to you guys.

What’s so magical about Gliffy and these diagrams? It’s that you can create and edit the diagram on the wiki page. When you view the diagram, it renders as a JPG on the web page. But if you have wiki permissions to edit the page, you can edit the diagram too. The Gliffy drawing interface is very intuitive to anyone who has used other drawing packages. This means that the drawings are “part” of the wiki — anyone can update them (permissions permitting) at any time, from any place.

Where do other technical writers get their examples?

I’d be really interested to hear where you glean your information from, especially if you’re in an agile environment or writing the documentation from scratch, with very little information falling down the traditional SDLC waterfall to land neatly in your pool of words.

We’re not business analysts, so we don’t have the time to do a full use case analysis or requirements investigation. But we often do need concrete and real examples. Has anyone else mined a bug tracker, walked a wiki or surfed a user forum to find this sort of information, and do you have any other handy tips?

An illustrated use case for this blog post?

A termite nest on a tree in Manly Dam Park (near Manly, NSW, Australia):

Keeping up with the younger Crowd

One of the best things about technical writing is the variety it offers: who you work with; the style of writing required; the type of products you document; your input into and impact upon the products themselves; the medium you use, and so on. One of the products I work on is highly technical, and the documentation is funky that way too. The product is Crowd. If you find authentication, authorisation, single sign-on and user management sexy, then Crowd is for you. And the documentation would be your choice of bed-time reading.

This week we released Crowd 1.2, a major release with lots of new features. So we published many new and revised documents too.

Documenting this type of product is interesting. On the one hand, you get a kind of glow from belonging to the elite group of people who understand words like ‘Acegi’ and ‘OpenId’. You have the chance to indulge your natural inclination for long words and other esoterica. You may notice one or two creeping into this blog post On the other hand, in the documents themselves the trick is to know when to explain something and when not. After all, we have a savvy readership. I try to keep explanations short. Often all you need is a link to an authoritative website and an expansion of an acronym on first use.

Gourmet’s guide to a technical document: Mix the dry ingredients. Sprinkle in the acronyms. Pour the open source over the top.

Another interesting thing about this type of documentation is that the developers write much of the content themselves. As technical writer, I guide and tweak the content. When I can, I’m keen to jump in and test-drive the integrations myself before documenting them. But sometimes that’s not practical or efficient.

Wikis are great for collaborating like this. I might kick off a document by creating the skeleton structure. Then the developer writes the first draft. I jump in and tweak some things. The development lead and another technical writer do an in-depth review. And there you have it, a document to suit the epicurean taste.
Sometimes, you can even make the document look pretty:

Ain’t that just copacetic?

Have you noticed that your brain starts shooting off at a tangent when you’re writing dry technical kind of stuff? I had to explain ‘Acegi’ in the Crowd release notes:

Crowd 1.2 provides a built-in application connector for Acegi, a security solution with a particular emphasis on Spring Java/JEE applications.

Here’s what my gray matter kept insisting was relevant:

Spring has sprung, da grass is riz

I wonder where da boidies iz

Da boidies is on da wing

Don’t be absoid

Da wings is on da boid

That’s a jingle that my dad recited to me when I was just a kid. It’s spoken with a cockney or Bronx accent. Evidently the verse’s origins are obscure, though it’s often quoted, and sometimes cited as an anonymous work called ‘The Budding Bronx’. Isn’t it weird how such things stick in your head? A blog is a great place to get rid of such insistent promptings from the subconscious. The jingle would probably, though not indubitably, be considered out of place in the Crowd docs.