FedEx 12 Delivery - Atlassian WTF (guided help tutorials)

This is a delivery note for "Atlassian WTF", or the Atlassian Webapp Tutorial Fantastique, scheduled for Atlassian FedEx 12.

On this page:

The problem – Atlassian WTF??

Your webapp has an elegant intelligent UI. It's fast, it's unobtrusive, and people who know it love it. But it's so unobtrusive that new users don't know where to start.

The solution – Atlassian WTF!!

Atlassian Webapp Tutorial Fantastique. Do it while you learn!

Atlassian WTF will consist of a set of help scripts for each Atlassian application, starting with a couple for JIRA and Confluence.

Each script guides you through an activity. You complete the task, on your live Confluence or JIRA site. So you're not reading documentation, reading help or watching a video. You're not working on a sandbox or test site. You are actually getting the job done and learning at the same time.

Delivery part 1 – Confluence "Create a space WTF"

^{Confluence 3.0 (localhost standalone)}
The WTF fairy is a photo of my earring.

Use case:

I've never used Confluence before.

Now I have to create a wiki space for a demo that starts in 15 minutes.

Confluence WTF?

Screenshots (click image for slide show):
These are just some of the screenshots from the script, showing the basic format, some decisions, and the offer of step automation.

Delivery part 2 – Confluence "View all blog posts WTF"

^{Confluence 3.1-m2 (localhost plugin dev environment)}
Kicked off via a Confluence menu item. Yes, I can do plugins now too

Screenshots (click image for slide show):

Delivery part 3 – JIRA "Where has Create Issue gone WTF"

^{JIRA 4.0.0-Beta2-#432 (EACJ)}
Giving JIRA the last word.

Screenshots (click image for slide show):

The Tool - SHO Guide

I decided to try SHO Guide from Transcensus. It allows you to create the scripts and publish them. You can download SHO Guide for a free evaluation.

Distribution and Use Cases

SHO Guide allows you to publish your scripts, creating a file with extension ".sho". The SHO Player reads and executes these files.

Standalone SHO file — For support and evaluators

• Send the SHO file to a customer via email.
• Attach the SHO file to a JIRA issue.
• Attach the SHO file to a wiki page.

Menu option — For online help

• Create a plugin to make the SHO files available from the application's menu (e.g. the Confluence "Tools" menu) or on a separate application screen.

FedEx Aims

Why did I choose this project for FedEx?

• To evaluate the SHO Guide tool and assess its suitability for our purposes.
• To demonstrate to other Atlassians what we mean by "guided help" and how it might be useful in our products.
• To prompt discussion on whether Atlassian should develop its own version of guided help for one or more products.

Future Possibilities

What the final, full product would look like:

• Atlassian WTF will consist of a set of help scripts for each application (JIRA, Confluence, etc).
• Confluence WTF will consist of a set of scripts for Confluence. Each script will guide the user through a specific use case, such as creating a space or retrieving your draft after an edit failure.
• The scripts may be available in various ways:
  • From the Confluence "Tools" menu, if enabled by the administrator.
  • As standalone executables that you can run from your desktop.
  • Sent to the user via email or attached to a JIRA issue, as part of a response to a support request or evaluator request.

If we decide to pursue this project, we need to:

• Decide whether to use SHO Guide, another tool or self-written guided help.
• Investigate the full capabilities of the tool we choose. For FedEx, I could only look at the basics of SHO. There is a lot of SHO training and documentation that I have not read. The Transcensus team, makers of SHO, have also contacted me a few times within the short FedEx timeframe offering further advice and keen to know how the project is going.
• Investigate any potential problems, such as security and performance.
• Investigate how robust the scripts are to product upgrades e.g. the move from Confluence 3.0 to Confluence 3.1.
• Write more scripts for Confluence and other applications.
• See if we can package the scripts as a plugin, making the scripts available in the menus via either a multi-layered menu or via a separate page/tab.

Evaluation of SHO

Requirements

Users will need:

• SHO Player – Free, and easily downloadable.
• The SHO script files – These could be hosted on our documentation pages, sent to customers via email, attached to a JIRA issue, or even available from the application menus (via a plugin)

Authors will need:

• SHO Guide – At time of writing, the cost of an authoring licence is $1995 per person p.a. See the Transcensus web site for current pricing.

Goodies

SHO is cool. Definitely worth evaluating for your own purposes.

• SHO authoring is very easy to learn. You'll have your first script in half an hour.
• The authoring environment is satisfying and fun to use.
• Technical writers and support engineers can create scripts and ship them independently of the development teams.
• SHO "filters" and "paths" are awesome. You can make your script react to various key strokes (e.g. when the user clicks the Tab key to move to the next field) and you can define paths for the script to follow, based on input from the user.
• SHO offers lot more capabilities I didn't have time to try e.g. you can include sound, video and documentation into your script.
• The Transcensus guys contacted me personally by email, to find out how the evaluation was going. When they heard that it was for a FedEx project, they were quick with offers of assistance.
• SHO handles a few different application types, as well as web applications. (I was interested only in the web side of things.)

Limitations

• SHO supports IE only.
• If running on Windows Vista, you must disable IE's "internet protected" mode when using the SHO Guide authoring tool. Otherwise SHO Guide does not recognise your clicks.
• You cannot have Firefox running at same time as IE, when using SHO.

Other Oddities

These are just a couple of things that could be better or need further investigation. Remember, Atlassian FedEx day is just 24 hours, so I didn't have time to go into anything in depth.

• Sometimes the SHO bubbles pop up in the wrong spot on the page. I'm not sure why yet. Requires further testing.
• The default bubbles are a bit ugly. It would be nice to have a thicker border, for example. But I haven't yet explored all the possibilities for customising them. I did get a nice effect by using the product-specific colours our Design team has created for our product branding.

Other Tools

There are two other tools that I know of, that produce similar guided help scripts:

• Active Guide from Rocket Software.
• eTracker and Click'nNav from Solan Technologies. I sent off a request for information to Solan Technologies, but haven't received a response.

SHO was the easiest to try, because it's easily available for download and evaluation.

Want to Read More about the Authoring Environment?

I've posted some screenshots and words about the authoring tool, SHO Guide, in my personal blog.