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

(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

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

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

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

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

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

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.

Book review – Conversation and Community by Anne Gentle

I’ve just had the pleasure of reading Anne Gentle‘s book, Conversation and Community, The Social Web for Documentation. I highly recommend it. The book is brim full of useful information and, even better, great ideas. This blog post is about some bits of the book that were especially interesting to me. When you read the book, you’re sure to find other sections that tickle your fancy or kick-start a killer idea 🙂

Conversation and Community by Anne Gentle

The book arrived in the middle of a busy week. My first impressions were: Yay, it found it’s way to Oz so quickly! Then I opened the package and saw the cover. You can almost taste the chocolate. Those people are all interacting with each other, great picture. What sort of keyboard is that — not QWERTY? Ah, the credits say it’s Danish. Cool.

It’s all about ‘now’

What really hits you when you read the book, is that the content is very current. It refers to blog posts written just a few weeks ago! You get the feeling that you’re engaging in a conversation with Anne and the other people she mentions, right now. You could go and comment on the blog posts and still be relevant. Awesome.

The foreword, by Andy Oram, sets the scene perfectly. Great opening: “A few years ago, this book could not have been written… A few years from now this book will be unnecessary… You are fortunate to have this book at this moment, for you can lead the next generation of information providers into the era of expert/amateur interaction.”

It’s all about ideas

Here’s a tip: When reading this book, have a notebook with you. The ideas will just keep popping into your head. For example, chapter 2 is a useful whiz-through of concepts and tools in the social web. Sprinkled throughout the chapter are some neat tips. It’s well worth a read, even if you already know most of the tools and concepts.

One idea I’d like to try, is using a Twitter feed right on the documentation pages as a way of displaying tips and FAQs. I haven’t quite figured out how to get the technology to do that for me. We need a Twitter widget for the wiki — one that shows a stream of tweets rather than just one tweet. But it’s almost possible. Then our community authors could tweet tips as they work!

Heh, this idea tickled my fancy: something to try when you’re struggling to write in a casual, simple style. Stick a picture of someone you know on your computer screen and pretend you’re explaining the concepts to them. (Page 23.)

Technical writers are in there, boots and all

Anne makes some excellent points about how our skills are transferable to the social web, particularly in integrating the social network into user assistance. (Page 25.) Key to the book is the point that readers of user assistance don’t usually care about where the information came from or who wrote it, provided it does the trick. (Page 9.) Our role includes taking this idea on board and working with the broader scope of available information.

That’s a bit daunting, but the book goes on to give guidelines on how to jump in, boots and all. Page 72 describes some participation models, and the following pages have pointers to getting involved in the social media.

How about style and standardisation? Those are endlessly debatable 😉 and particularly in the less formal online / social environment. Undaunted, Anne has written up some good guidelines. (Pages 184-8.)

Working with communities is an art unto itself

Anne encourages us to get started by listening, observing and then building up our own participation slowly, before establishing a community ourselves. Once we have a documentation community, there are ways to check the social weather in the community and keep it sunny. (Page 109.)

Anne notes that we can probably expect a small percentage of contributors, and that we should value them highly. She mentions the 90-9-1 rule: 90% reader, 9% infrequent contributor, and 1% active contributor. (Page 160.) This rings true with our own experience at Atlassian, of community contributions to the documentation. It’s interesting to see the researched statistics. And we do value our contributors, very highly. ♥

Here’s a clever metaphor cum reference to current wisdoms: “Teaching the community to fish (for information) feeds them longer than just answering questions without citing how you learned the information yourself.” (Page 137.)

Booksprints sound like so much fun, and so productive. I’d love to get involved in one. So it’s great to see some detailed advice from a book sprint diva. 😉  The book has a long section (pages 112-124) going all the way from planning, through logistics to just plain fun.

So, did I like it?

Conversation and Community by Anne Gentle

Yes! The book is easy to read, authoritative yet friendly. That must be a hard balance to strike. Anne’s command of her subject, her wide-ranging interests and her skill with language make the book a pleasure to read. For example, I love the combined precision and pragmatism of this statement:

“This chapter contains a frozen-in-time list of some terms and tools in 2009 that are related to social media.” (Page 29.)

And the interesting perspectives on social contributions to Shakespeare’s scripts and the OED, gleaned by Anne from Alan Porter. (Page 66.)

Anne has tweeted that she’s experimenting with virtual book signings. Cool idea! I’m hoping her experiment succeeds and I’ll get a virtual signing of my copy too. Go Anne!

What other people are saying

I’ve purposefully restrained myself from reading anyone else’s review of Conversation and Community, so that I could write mine with an uninfluenced mind. Next I plan to read what everyone else has to say. A quick search reveals:

• The book’s overview page at publisher XML Press.
• Stewart Mader’s review at Future Changes.
• Jefro’s review at Jeff’s Open Source Resource.
• Various reviews at Amazon.com.
• Ellis’s review at Cherryleaf Technical Authors Blog.
• Sarah O’Keefe’s review at scriptorium Palimpsest.
• Rhonda Bracey at CyberText Newsletter.
  

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

Half an hour left. The pace is frantic now:

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

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

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 😉

Atlassian technical writers on agile methodology

Our marketing and website development teams have been working hard for the last few months, putting together a collection of videos, stories and tips about how Atlassian does agile. The result is an awesome section of the web site, called “agile@Atlassian”.

Today, the technical writer section was published, complete with videos: The Technical Writer & Agile Technical Writing. I just love the opening lines:

Technical writers are part detective and part reporter. Sleuthing through code changes, tech writers constantly sprint to assure that every feature in an iteration gets converted into instructions that any user can follow.

I think I detect Ed’s style there. 🙂 Ed is our team leader. He and I are featured in the agile@Atlassian tech writing section. There are also plenty of goodies for those not fortunate enough to be technical writers, such as testers, programme managers, team leads and of course, developers.

The best bit is that these are videos of and words from work-in-the-trenches, common-or-garden Atlassians. Like me.

So yes, there’s a video of me too. It’s creepy seeing yourself on video. When I first saw it, I had to resort to some strong chocolate before regaining my usual joie de vivre. 😉

I hope you enjoy the site! Go tech-writers@agile@Atlassian.

Author and date at top or bottom of wiki page

Do you prefer to see the author and date at the top or bottom of a wiki page? I did a quick Twitter poll a couple of days ago. Here are the results.

If you like, you can add your thoughts via a comment on this page. I’ll update the page in a week or so with those results too.

Background to the poll

In the current version of Confluence wiki, the author and date are shown at the top of the page. It shows the name of the person who created the page, the date the page was last updated, the person who did the last update and some other options. Here’s what it looks like:

There’s ongoing discussion at Atlassian about creating a documentation-specific theme for Confluence. Don’t get excited 😉 There are no definite plans. We just like throwing ideas around to see what flies. Another perennial discussion is about where the author tagline should go. Top or bottom.

The Twitter poll

I asked the question:

Quick poll: Using Confluence wiki for documentation, do u prefer author + date at top of page (as now) or at bottom?

Summary of results: There were 10 replies, plus my own vote makes 11 votes.

• Top: 10
• Bottom: 1 (but not for documentation)
• Other: 1

That adds up to 12 votes, because one person prefers the tag line at the top for documentation and at the bottom otherwise.

Updated Friday 7 August: I’ve had two extra replies, bringing the total to 13 votes and the preferences to:

• Top: 12
• Bottom: 1 (but not for documentation)
• Other: 1

Details of the responses

Thank you to everyone who answered! It was fun and interesting. Here’s what everyone said.

From Alister Scott:

prefer the top of the page.

From Ellen Feaheny

Absolutely on top – Twiki places name/date on bottom and it is just weird … it’s not authors, it’s collaborators (and chgs)

From Sean Winter:

for documentation – top, for web style presentation – bottom

From Tobias:

I prefer it at the top. I am used to it, because all papers are written that way.

From Dave O’Flynn:

As now – at the top

From Guy Fraser:

Depends on how the site is being used – sometimes at top, others at bottom, sometimes in sidebar, sometimes removed completely

From Keith Brophy:

At the top of page (as now)!

From aarontay:

I prefer the author+date at top for confluence wiki.

From Bryan Guffey:

Would rather have up top!

From Eric Dalgliesh via Facebook:

Top, definitely.

Updated Friday 7 August: I’ve had two extra replies:

From Joshua Wold via our internal wiki:

The top absolutely. Interesting poll Sarah.

I want to see the latest of what is going on with the particular topic and the author and last editor are very useful for this. Personally I’d love a mouse-over to show me more of the recent history of the participants on the topic (activity steam for a page in a way).

From Christina Bang, as a comment at the bottom of this blog post:

At the top, for sure!

What do you think?

Purely out of interest, I’d love to know what you think. There’s no definite plan at Atlassian to do anything about this any time soon 🙂 I’m asking this question off my own bat, because I’d like to know what other technical writers and interested people think. Here’s something to consider too: We’re looking at this from the point of view of technical authors. The tag line contains valuable information for us. I wonder what the readers would prefer?