Rewarding humour in online help forums

One of the contributors in our online question-and-answer forum, Daniel Stevens, has a quirky and amusing style of writing. His entries are always relevant, but he nevertheless manages to inject some humour that makes for easy reading and invites quick responses from other forum users.

My first aim in writing this post was to share the fun of reading Daniel’s forum entries. Then I thought about the bigger picture. The idea of humour in an online help forum is an interesting phenomenon, especially for technical communicators.

First, the fun. Here’s a screenshot of one of Daniel’s posts, called Is there a flood control function on the “Like” button?

And here’s another, Why can’t I upload icons for new priority, issue and workflow step entries?

Have you encountered similar witty posts in user forums? What do you think about the idea of rewarding such entries? This particular forum, Atlassian Answers, is clever about awarding badges and points for popular questions and good answers. Each contributor to the forum builds up a “karma score”, which encourages people to keep contributing. So, should there be a specific score category for funny entries?

As one of my colleagues pointed out, the social review site Yelp invites readers to click a button saying whether a review is “useful”, “funny”, or “cool”. Should a user forum do the same?

If the forum starts rewarding humour entries, might that lead to irrelevant and silly content? My opinion is that there may be some of that, but on the whole people are in the forum to get a question answered, or to help other people with their questions. A touch of humour just makes the posts flow better, and most people will recognise that fact. People who don’t have a bent for humour won’t bother to spend the time trying to be funny. Or is that a naive assumption? 🙂

How to add an image caption in Confluence

A customer, Chris Ridgeway, added a comment to the Confluence 4.1 release notes yesterday, saying that the release notes implied that you can add a caption to an image. But how? The good news is that you can do it, and it’s pretty snazzy once you know how!

In short: Use the “Instant Camera” image effect, and add your caption as a comment on the image attachment. (There’s a step-by-step guide later in this post.)

It took me half an hour to figure out how to do it. Like Chris, I was baffled. I applied the “Instant Camera” image effect, because the Confluence menu option implies that you can have a caption:

Then I tried clicking the image, double-clicking, right-clicking… Nada. So I tried going back into the image properties panel, in case another field had magically appeared there. Nope.

But I could see the caption in the screenshot in the release notes, so I wasn’t going to give up. Eventually I sat back and thought: If I were a Confluence engineer, what existing field or attribute might I decide to use as the image caption? I tried using wiki markup to insert the image, which gave me the power to add the HTML “title” and “alt-text” attributes – but they didn’t show up as the image caption.

Then it came to me: What about the attachment comments? Eureka!

Step by step

I’m using Confluence 4.3, and image captions have been available since Confluence 4.1.

Here’s how to add a caption to an image on a Confluence page:

1. Edit the page.
2. Click the image to see its properties panel.
   
3. Choose Effects in the image properties panel and choose the Instant Camera image effect.
   
4. Save the page.
5. Choose Tools > Attachments to go to the “Attachments” view of the page.
6. Choose Properties on the line that contains the image file name.
7. Add a comment and save the attachment properties. My comment is “Yum!”
   

The text in your comment will appear as the image caption:

You’ll need to re-do the comment each time you upload a new version of the image.

And yes, I have now updated the documentation. Thanks Chris Ridgeway for asking this question and sending me on a mini treasure hunt. 🙂

Documenting a mobile interface using Chrome’s user agent setting

I’m documenting the new mobile interface for the upcoming release of Confluence 4.3. At first, I kept grabbing my iPhone to get screenshots. Then a colleague pointed out that I can use the “user agent” setting in Google Chrome to emulate a mobile device. Very handy indeed!

With Chrome’s user agent setting, you can make your desktop browser pretend that it’s something else. It can masquerade as Internet Explorer (and everyone wants to do that 😉 ), Firefox, iPhone, iPad, Android, and other devices.

Here’s how:

1. Open a web page in Chrome.
2. Press Ctrl+Shift+i to open the developer tools panel at the bottom of the Chrome window.
3. Click the settings icon (a cog) at bottom right of the developer tools panel.
4. Click the ‘User Agent’ tab.
5. Select the ‘Override User Agent’ check box.
6. Choose a browser and version from the dropdown selection.
7. Make sure the ‘Override device metrics’ check box is also selected. This allows Chrome to control the size of the viewport, based on the user agent defaults.
8. If you want to further tweak the size of the viewport, change the ‘Screen Resolution’ values.
9. Refresh the screen (press F5) to make sure all the new settings take effect.

Now you can interact with the web page as usual. The web app will think that you are using a mobile device, and will offer the corresponding options.

This is perfect for me. I want to use my desktop to develop content, while documenting a mobile interface. I’ve set the user agent to ‘iPhone – iOS 5’ and tweaked the screen resolution to get good sized images.

This screenshot shows the Chrome developer tools panel at the bottom. The top section contains a web page, viewed as if from a mobile device:

Here’s another screenshot, showing the same developer tools panel at the bottom. I’ve moved to the flyout menu offered by the website when accessed by mobile devices, as you can see in the top part of the Chrome window:

“Upcoming release” – does that mean I’m letting the cat out of the bag? 🙂

Ha ha, no. The Confluence mobile features are already visible in the beta release notes.

Tsk tsk Google

A very nice feature, but watch those inconsistent caps. 😀

Version management gets serious with Confluence Scroll Versions plugin

The team at K15t Software have just announced the first production release of Scroll Versions, an exciting new plugin for Confluence wiki. Our technical writing team has been working with the K15t guys on specifying and testing Scroll Versions. We and K15t are delighted with the 1.0 release. What’s more, K15t have exciting plans for adding even more features to the plugin. These features are what technical writers dream of. 😉

This video, produced by K15t Software and narrated by Kelly McDaniel, gives an excellent overview of the plugin’s functionality.

Why I’m excited about Scroll Versions

For me, the selling point is version management. And I’m over the moon about the enhanced features planned for future release.

What’s new about the version management offered by Scroll Versions? The standard Confluence functionality (without any additional plugins) includes a good solution for version management of single pages, and of entire manuals:

• At the page level: Every time someone updates a page, Confluence saves a new version of that page. You can see the page history, compare two versions to see what changed, and revert to a given version at any time.
• For version management of a manual or a set of documents, we use spaces. For each major release of the product, we copy the contents of a documentation space to a new space and brand it for the new version of the software.

But it’s difficult to mark a set of documents for publishing in a batch. For example, you may want to publish a page of release notes and a couple of minor updates for a point release of the product. Or you may be developing a new subset of documentation, not related to a product release, and you want to publish all the pages at once. Or, of course, you’re working towards a major software release and need to bundle a batch of new pages, updates and deletions for publication on release date.

In an agile environment, you may need to have a number of versions – let’s call them “branches” – running at the same time, each for a different feature. And you need to publish those versions – or “merge those branches” – at fairly arbitrary time intervals.

This is what Scroll Versions can give us now. You can have a number of versions of your documentation in draft state. You can create and manage multiple versions of the documentation, all in one Confluence space, all at the same time. A version consists of a set of new and updated pages, and even page deletions.

When you’re ready, you can publish a given version of the documentation. The effect is that people who view the content of the space will see that version only.

The other versions, both past and future, remain available in the space. You can publish any version at any time. You can even go back to a previous version. You can publish your version to the current space or to a new space. The versions are incremental. For example, version 1.2 of your documentation will include all the updates from version 1.1. You can change these dependencies at any time, making version 1.2 dependent on version 1.1.9 instead of 1.1, for example.

A future release of Scroll Versions will add conditional publishing, as well as the ability to publish from one space to a different, already existing space, thus merging the new version with existing content in a different space.

This screenshot shows the Scroll Versions configured in my test documentation space. I have set up a few versions:

• 1.0 – the original version of the documentation that existed when I installed Scroll Versions.
• 1.0.1 – a bug-fix release, based on version 1.0. This is the currently-published version of the documentation. I used Scroll Versions to publish it.
• 1.0.2 – an upcoming bug-fix release, based on version 1.0.1. This version is not yet published.
• 1.1 – the next major release, based on version 1.0. See the nifty branching visualisation to the left of the version numbers!

I would probably change the dependent version of my 1.1 release a few days before publishing it. I would make it depend on the last bug-fix release, which may at that stage be 1.0.9, for example. By changing the dependency, I make sure that version 1.1 picks up all the changes made in versions 1.0 to 1.0.9.

Other goodies in this release

Using Scroll Versions, you can have more than one page with the same name in the same space. Yes, duplicate page names are now possible.

There’s also a new macro for enhanced content reuse. And you can add permanent identifiers to pages, which stay the same across multiple versions and different spaces – useful when you want to use the wiki  as an online help solution.

How to set up and use Scroll Versions

I’m using Confluence 4.2 and Scroll Versions 1.0.1.

Note: For the purposes of this post, the words “add-on” and “plugin” mean the same thing. The Atlassian Marketplace refers to “add-ons” and the Confluence user interface calls them “plugins”. The term “add-on” is broader than “plugin”, since an add-on can refer to other types of extensions. Scroll Versions is a plugin.

If you don’t already have Confluence, you can install an evaluation Confluence site and use it for 30 days free of charge. It’s quite easy to install Confluence on a laptop or desktop computer:

1. Go to the Confluence download page.
2. Download the installer for your operating system.
3. Run the installer and follow the instructions it gives you.
   • Choose the default options for an evaluation installation.
   • When the installer has finished, it will open the Confluence setup wizard in your web browser. Follow the instructions to configure Confluence, again choosing the default options for an evaluation installation.
   • Choose to include the sample data. This will give you a wiki space full of content that you can play around with. It’s called the “Demonstration” space and has a space key of “ds”.
   • Generate an evaluation licence key as prompted, and paste it into the Confluence licence key text box.

To set up Scroll Versions on your Confluence site:

1. Go to the Scroll Versions plugin page on the Atlassian Marketplace.
2. Choose the big blue button that says “Free 30 Day Trial”.
3. Follow the instructions as prompted, to do the following:
   • Generate a 30-day license for Scroll Versions.
   • Download the plugin (a JAR file).
   • Install the plugin via the Confluence administration screen.
   • Add your Scroll Versions licence key via the Confluence administration screen.

Now you have Scroll Versions on your site. The next step is to enable it in your documentation space:

1. Go to a page in the space. If you’re using an evaluation site, you can use the Demonstration space at this URL: http://localhost:8090/display/ds
2. Choose “Browse” > “Scroll Versions”.
   
3. Follow the instructions as prompted, to do the following:
   • Activate version management in your space, and choose the version for the content currently in the space.
     
   • Define the groups of people who will be able to write version-controlled content (the “Authors”) and the people who will be able to configure the Scroll Versions behaviour in the space (the “Doc-Admins”). Hint: If you’re evaluating the plugin on a test site, it’s easiest just to assign the “confluence-users” group to both these roles. The “confluence-users” group consists of everyone who has permission to log in to your Confluence site.
     
   • Determine whether your space should allow duplicate page names.
     
   • Save your changes.

Your space is now configured to use Scroll Versions for version management. The next thing is to add a version or two, and start playing with them.

To add a new version of your documentation in your space:

1. Go to a page in the space.
2. Choose “Browse” > “Scroll Versions”. You will see that there are now two big green buttons, one called “Manage Versions” and one called “View Configuration”. The second button takes you back to the configuration steps that you’ve just done above. If you clicked it, come back again!
3. Choose “Manage Versions”.
4. Choose “Add Version”.
5. Add the details for your new version. For example, it may be version 1.0.1, which is based on version 1.0.
   
6. Add a couple more versions, just for something to play with.

When you go back to the pages in your space, you’ll see the Scroll Versions information panels at the top of each page. The version information panels and options are visible only to the people in the groups you specified as Scroll authors or doc-admins. Other viewers of the space will see just the wiki page, as usual.

Now that you have Scroll Versions set up, it’s a good time to watch that video again (at the top of this post) and then start playing with the product.

More reading, and feedback

This is K15t Software’s blog post announcing the release:  Announcing Scroll Versions – Concurrent Version Management for Atlassian Confluence.

The documentation is here: Scroll Versions Documentation.

The team at K15t Software are very keen to have our feedback. Happy wiki version management!