ffeathers — a technical writer’s blog

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
  

Do you find it more difficult to put a document together when you’re not feeling all that motivated? I do. That’s because technical writing is a creative endeavour. You need a bit of flair to write those low-fat, high-fibre, not-entirely-sugar-free documents.

Some people may think technical writing is dry, boring and mundane. I don’t find that. It’s challenging and rewarding, and gets you in the zone as much as any other creative activity.

You need to engage the imaginative side of your brain to find the right words, to cut out the dross, and most importantly to put yourself in the place of your reader. Auto-generated documentation definitely has its place. But the best Javadoc includes some human-spawned words, clarifying the purpose and context of a class, method, etc.

After all, our readers are human, not machine. If machines did everything, there’d be no need for documentation. Or chocolate. Or anything.

Back to the trees

It’s a while since I’ve put a picture of a tree on my blog. What do trees have to do with documentation? Well, stretching for a connection: From time immemorial people have been writing on bark

I was out walking in the Ozzie bush this morning. Here’s an Old Man Banksia, being as picturesque and in-the-moment as they always are:

Is technical writing creative?

Here’s a gum tree in flower, with a rainbow lorikeet soaking up the zen:

Is technical writing creative?

Here’s the same tree, with Sydney city in the background and the lorikeet leaving:

Is technical writing creative?

My favourite principle in the Agile Manifesto is that you get good people, put them in a good environment and then trust them to do a good job.

A “good environment” — that’s where chocolate comes into it.

At the office we have cupboards full of the stuff. Undeterred by such abundance, the Technical Writing team also goes on regular “doc hot choc” outings. We usually go to our local Lindt Café. Sometimes we even allow one or two hangers on, like a developer who has written a Confluence plugin just for us.

“We have come to value chocolate over extensive verbal compliments.”