Blog Archives

Another Atlassian FedEx Day and a Confluence gadget on the way

A few months ago I wrote about my first Atlassian FedEx day ever. Now I’ve survived another. Plenty of dust, sweat and tears, and plenty of laughs, later, I have a brand new Confluence gadget to boast about. Well, actually I have 3 halves of a Confluence gadget and lots of lessons learned.

My aim for this FedEx Day was to learn more about developing gadgets. I’ve created a gadget before, but it was a generic Google gadget and not specifically an Atlassian gadget. Of course, if I can get a useful gadget working too, that would be awesome.

I’m part way there.

My JIRA Tips Gadget

Just so you know: It’s nowhere near ready yet.

The user story: People want to see JIRA hints and tips on their JIRA dashboard, rather than having to find their way to our documentation. We want the hints and tips to be housed on our documentation wiki, so that we can update them easily. People also want to see Confluence hints and tips on their Confluence dashboard, and Crucible hints, and so on.

The solution: Develop a “Tips” gadget for each product, starting with the JIRA Tips Gadget.

  • The gadget gets the tips, one at a time, from our documentation wiki, affectionately known as CAC.
  • On CAC, we have a set of tailored tips for JIRA, another set of tips for Confluence, etc. These tips can be part of the documentation too, provided they keep the required (minimalist) format. We’ll store them as children of a particular page, so that the gadget knows where to get them.
  • People can:
    • Add the JIRA Tips Gadget to their JIRA dashboard.
    • Add the Confluence Tips Gadget to their Confluence dashboard (by customising their Dashboard welcome message) or a wiki page.
    • Add any of the “Tips” gadgets to iGoogle, Gmail, etc.

Things I learned the hard way

FedEx tip 1: Don’t shut down your environment at the end of day 1. I made that mistake, and then spent two hours getting it back on Friday morning.

FedEx tip 2: Don’t install a Confluence plugin containing a gadget module that refers to a gadget spec residing on the same Confluence instance. I stored my gadget spec (XML file) as an attachment to a Confluence page. That seemed handy.  But the startup procedure found the gadget plugin and went looking for the gadget spec. It waited and waited and waited… ;) Eventually I reinstalled Confluence and recreated all my configuration and data. Hence the two hours on Friday morning.

How far did I get?

The plan was to start with a very simple gadget and gradually make it more complex:

  1. First a URL-type gadget that does a straight grab of content from a page.
  2. Then an OpenSocial gadget (i.e. an HTML-type gadget), but still grabbing the HTML off the page.
  3. Lastly a full-blown OpenSocial gadget using the Confluence REST API.

1. The URL-type gadget

This is a quick and dirty solution using:

  • A gadget with content type=”url”.
  • An {include-random} macro in Confluence.

On my JIRA dashboard, the gadget shows a random tip on each refresh:

Another Atlassian FedEx Day and a Confluence gadget on the way Another Atlassian FedEx Day and a Confluence gadget on the way Another Atlassian FedEx Day and a Confluence gadget on the way Another Atlassian FedEx Day and a Confluence gadget on the way

The gadget XML is very very simple:

<?xml version="1.0" encoding="UTF-8"?>

<Module>
<ModulePrefs title="JIRA tips (URL gadget)"
height="400"
scrolling="true">
<Require feature="dynamic-height"/>
</ModulePrefs>
<Content type="url" href="http://my.Confluence.Server:8090/display/MYSPACE/MYPAGE" />
</Module>

In Confluence, we have:

  • A parent page with the following content:
    {include-random:MYPAGE|nopanel}
  • And a number of child pages, each one containing a single tip.

It’s not an OpenSocial gadget, but rather a gadget with a content type of “url”. The URL given is the address of the Confluence page that contains the {include-random} macro.

2. The HTML-type gadget grabbing HTML from a Confluence page

This is a quick and dirty solution using:

  • A gadget with content type=”html”, i.e. an OpenSocial gadget, but without REST. Instead it just gets the HTML from a Confluence URL. Next stage would be to parse the HTML to isolate the content of the wiki page.
  • An {include-random} macro in Confluence.

On my JIRA dashboard, the gadget currently shows the HTML for the full page and without special styling:

Another Atlassian FedEx Day and a Confluence gadget on the way

If it’s worth pursuing this type of gadget, I need to:

  • Parse the HTML to get only the page content.
  • Apply a style sheet.

3. The OpenSocial gadget using Confluence REST API

This is supposed to be the final, walking talking solution using:

  • A full OpenSocial gadget.
  • The Confluence REST API, rolling through all the child pages of a given parent page.
  • Something to convert the wiki markup into HTML.

At the moment, it’s still a quick and dirty solution using:

  • A full OpenSocial gadget.
  • The Confluence REST API, returning a single page.
  • HTML markup in the Confluence page content.

My REST gadget returns the page body as wiki markup. Here it is on my JIRA dashboard:

Another Atlassian FedEx Day and a Confluence gadget on the way

I don’t have time in FedEx to parse the wiki markup. So I cheated completely and put the HTML directly onto the Confluence page. So here’s what the gadget shows now in JIRA:

Another Atlassian FedEx Day and a Confluence gadget on the way

Of course, the Confluence page looks like nothing on earth:

Another Atlassian FedEx Day and a Confluence gadget on the way

I’d like to pursue the REST solution. I still need to:

  • Retrieve the child pages of the given page.
  • Render the wiki markup.

Bits and pieces

At the moment all three of my gadgets consist entirely of Javascript, XML and HTML. So the whole gadget is contained in the XML gadget spec. None of them (yet) requires a plugin. Gadget XML can be served from anywhere. I’ve stored mine as attachments to a Confluence page and serve them from there.

Phew

That’s Atlassian FedEx Day for you — quick and dirty and fun. Within the next few days, I’ll post a full report on our documentation wiki (CAC) that will probably include the gadget code (if I’m feeling brave enough to expose that to the world). I hope you’ve enjoyed reading about it and learned something along with me. :)

Update on 1 Feb 2010: I’ve posted the “Atlassian FedEx Delivery Note” for my project on our documentation wiki now too. It contains the gadget code: ShipIt 13 Delivery – JIRA Tips Gadget. (Updated March 2013: FedEx Day is now called ShipIt Day.)

SHO for guided help

“Guided help” – that’s when you actually do the task you need to do, and some helpful bubbles or other UI prompts tell you what to do next. You’re not reading documentation, reading help or watching a video. You’re not working on a sandbox or a test site. You are actually getting the job done and learning at the same time.

I’ve recently tried SHO Guide, a tool for creating guided help scripts. It was a lot of fun and a very worthwhile experiment.

In a nutshell, this is what happens: Using SHO Guide, you write scripts and publish them. This produces a “.sho” file for each script. Your customers then use SHO Player (freely downloadable) to play the script. It hooks into the UI of your application and guides them through the steps they need to take.

First impressions

SHO Player is a quick download (1.3 MB). Installation is painless (apart from the usual chattiness from my Windows Vista OS). SHO Guide is a longer download (60 MB).

When you get your SHO Guide licence key, username and password, you also gain access to the “Resources” part of the SHO web site. This has plenty of tutorials, FAQ, a support forum and information about training. The Quick Start tutorial is very good. Fast, with just the right amount of information to get you started. It guides you through creating a SHO script for Notepad.

Creating scripts with SHO Guide

You can record a series of steps, by clicking the “Record” button in SHO Guide and then performing the steps in the application you’re documenting. Then you can go back later to edit, insert or delete steps as required. This is very useful.

The SHO Guide authoring environment has a familiar look and feel to people who have used various types of authoring tools:

SHO for guided help

SHO for guided help

(Click the image to expand it.)

On the left of the above screenshot are the two scripts I’ve created, called “Create a space” and “View all blog posts”. Underneath the scripts are two more segments, hidden at the moment, where you can access extra step types and a library of images and other resources. In the middle is the bubble that the users will see, with various options for you to create conditional paths, filters and actions. It doesn’t take long before you know what’s what and where to find it.

The easiest way to start a script is to record it. Here’s a screenshot showing a recording in action:

SHO for guided help

SHO for guided help

In the above screenshot, I’m recording an activity on the Confluence dashboard, running in Internet Explorer. The red square shows the UI element that is currently in focus. At the bottom of the screen is the SHO Guide recorder panel, showing the key presses already recorded.  The icon of a video camera at far right means that the recording mode is active and ready for input. The icon changes to a hand when the recording is paused or busy.

Hint: It can take a while to save a recorded action. Wait until the hand changes back to a video camera before continuing with the next click or exiting from SHO Guide, otherwise your clicks may not be recorded.

The end result

Here’s a screenshot showing the starter bubble of a script I created for Confluence, helping people to create a wiki space:

SHO for guided help

SHO for guided help

The problem: You’re new to Confluence, or to another Atlassian application. You have to get something done, and you’ve no idea where to start. You’re panicking. You’re in a hurry. The UI is not helping, because it assumes at least a bit of knowledge. Atlassian, WTF??

The solution: Atlassian WTF!! The Atlassian Webapp Tutorial Fantastique. ;)

Curious about the fairy in the bubble? She’s the Atlassian Webapp Tutorial Fairy, of course. She’s also a photograph of my earring. You can add images, videos and documents to your SHO scripts.

Here are a couple more screenshots of the same script in action:

SHO for guided help

SHO for guided help

So the user would click the “Create a space” link, as prompted by the green bubble. Confluence then opens the “Create Space” screen and SHO supplies the next bubble, prompting them to enter the space name.

SHO for guided help

SHO for guided help

In the screenshot below, see how you can present a choice of paths to the user. In this case, the “Do It For Me” option launches a set of automated steps — another cool feature of SHO.

SHO for guided help

SHO for guided help

The user also has the SHO Player toolbar, allowing them to pause or stop the script:

SHO for guided help

SHO for guided help

Want to see and read more?

Experimenting with and evaluating SHO was my Atlassian FedEx Day project. There are more screenshots in my FedEx 12 delivery note, as well as some notes about the requirements and limitations of the tool. What on earth is FedEx Day, you ask? It’s a period of 24 hours when Atlassians get to do something totally different from our normal day-to-day job, then present our findings to the rest of the company. It’s pretty cool. I wrote about it last week.

Wrapping it up

This was my first foray into guided help and into SHO. A big thank you to Matthew Ellison for mentioning SHO in his presentation on context-sensitive help at AODC 2009. (I wrote about it too.)

BTW, this was just an experiment. The scripts aren’t by any means production ready.

I haven’t had time to investigate SHO in detail. There are many possibilities, such as including sound, video and documents into your scripts, adding specific action types, trapping errors issued by the app, and so on. SHO Guide is easy to download and you can evaluate it for free for two weeks. The Transcensus guys, makers of SHO, have been very friendly and free with offers of help and discussion. Definitely worth a try. Fun too. That’s what it’s all about, huh.

Technical writers do Atlassian FedEx Day

Every three months or so, Atlassians go mad. The frenzy lasts 24 hours, and it’s called “FedEx Day”. Up to now, the insanity has affected predominantly the developers. This time the tech writers went bonkers too. I survived to tell the tale, just barely. Here it is.

What is FedEx Day?

Atlassian is the software-development company I work for. FedEx Day lasts from 2pm on a Thursday to 2pm the next day. In those 24 hours, you get to develop anything you like. At 3pm on Friday, the presentations start. You get 3 minutes to present your project to the rest of the company. It’s called FedEx Day because your project must be delivered overnight. The winning project is decided by vote.

It’s a pretty cool idea. You get to try something that you wouldn’t normally do in your day-to-day job. The result just may turn out useful for you, your colleagues and the company. It often does. Some FedEx projects end up as part of Confluence, JIRA or another product.

For the most part, it’s the developers who go nuts. But three FedExes ago, a technical writer won the vote for best FedEx project! That was Ed, our team lead, who wrote a Flash game called Atlassian Invaders.

How did I do?

My report is a mixed bag of nuts. The first part of my FedEx was great. It was so much fun, spending a work day experimenting with something new. I played with some cool technology and managed to get some nice results. I’ll write another blog post soon, about the project itself. Here’s a tantaliser: my project is called,

Atlassian WTF ;)

The second part was the presentation. I was really nervous about that, right from the start. And with good cause, as it turns out. FedEx Day presentations are notorious for going wrong. Mine did. The first time I tried it, my demo stopped working each time I plugged the projector cable into the PC. Thank you FedEx gremlin!

Matt, the FedEx Day coordinator, was kind enough to let me have a 2nd attempt. I started up the demo software first, then plugged in the projector.  This worked better, but I ran into more problems later in the demo. And I turned into a wobbly jelly, something I’m apt to do. Ah well, at least I was able to demo the general idea. I needed a good stiff Coca Cola after that!

What about the other technical writers?

They were right there, in the middle of the madness. Giles converted a Confluence user macro (the {expand} macro) into a macro plugin. That’s pretty awesome. Alas, the FedEx gremlin attacked him too. His macro refused to work for his presentation. He later discovered it was because the demo machine was running Safari, while he had been testing in Firefox.

Andrew wrote a specification for automating some of our Confluence documentation release procedures. We’re hoping this will be a useful tactic in persuading a developer to write the code. We’ve offered a chocolate bribe too. Is our optimism all part of the general madness? Watch this space ;)

Rosie started writing some sample Confluence content that non-technical evaluators can download and import into their Confluence installation. She tackled a sample intranet site and a documentation space.

Ed created a Flash game, where old-school die-hard anti-code-review developers battle it out against reviewers encroaching upon their code.

It was great to see the varied, interesting and valuable FedEx Day projects the technical writers up with. Go tech writers :)

The story in pictures

Friday morning, 5 and a half hours to go. Here are a few manic developers, with evidence of a hard night’s work in the foreground:

Technical writers do Atlassian FedEx DayTechnical writers do Atlassian FedEx Day

Technical writers do Atlassian FedEx Day

It finally happened. We’re going slightly mad. This FedEx Day was the first time that all the technical writers took part. Ed and Giles had done it before, but the rest of us were FedEx virgins. Here we all are, with other cross-product team members, all going just very slightly mad:

Technical writers do Atlassian FedEx Day

Technical writers do Atlassian FedEx Day

Half an hour left. The pace is frantic now:

Technical writers do Atlassian FedEx Day

Technical writers do Atlassian FedEx Day

Only too soon, the presentations start. We’re one wave short of a shipwreck:

Technical writers do Atlassian FedEx Day

Technical writers do Atlassian FedEx Day

We’re simply not in the pink, my dear:

Technical writers do Atlassian FedEx Day

Technical writers do Atlassian FedEx Day

There are more photos on Flickr. FedEx Day is fun. The presentation part of it is… nuff said. Maybe better next time. I think I’m a banana tree, and I’ll be there ;)

Follow

Get every new post delivered to your Inbox.

Join 1,389 other followers

%d bloggers like this: