Month: September 2009

Documentation at the Summit

I’m hoping to lead two sessions about documentation at the Boston Summit this year.  Hopefully I can garner some interest from the blogosphere.

First, I want to give a short talk on topic-oriented documentation.  This is a very different way of thinking about your documentation, and I’d like to introduce people to it and convey some best practices.  The documentation team went topic-oriented with the new Mallard-based Empathy Help this release cycle.  But topic-oriented isn’t limited to Mallard, nor is it only relevant to user help.  I’ll try to keep the concepts general, while still giving guidance for the real-world systems we use.

After that, I’d like to have about three hours to lead a docfest.  I will help you write or improve any piece of documentation you bring to me.  If you don’t have something in mind already, I’ll find something for you.  It does not have to be user help, and it does not have to be topic-oriented.  I realize this is a hacker’s event, so bring me your API references or developer tutorials.  We’ll turn it from a random collection of thoughts into a coherent document people enjoy reading.

If you’re interested in either, please leave a comment.  Or send me an email at shaunm at gnome dot org.

Yelp Live Help

By day, I’ve been learning my way around the awesome Telepathy framework as part of my work with Collabora.  By night, I’ve been busy hacking away on Yelp 3.0 (which, I don’t mind telling you, will rock).  And somewhere in between, I’ve been contemplating how to make Yelp telepathic.

Here’s the general notion: When the help just isn’t helping you, you’d be able to connect to Live Help, which would be something like a chat room, hopefully populated with people who want to help.  The Live Help chat would be attached to your Yelp window.  Other users would be able to see what document you’re looking at, and send you pages which would open in your Yelp window.

The Live Help channel would also maintain a list of comments made about pages.  So if somebody asks a damn good question, somebody could write something up in a comment on a page of the help document.  As soon as you connect to Live Help, you’d get all the comments stored in the channel for the document you’re viewing.

This is a very rough idea right now.  There are tons of technical and social problems that would have to be solved to make sure it works well.  I’m curious if people have any thoughts, opinions, or criticisms.  (And, by the way, we could totally extend this functionality to developer documentation as well, which I think would be awesome.)

Yelp 3.0: Location Entry

So I’ve begun picking Yelp apart in preparation for Yelp 3.0.  I’ve gotten to the broken-eggs stage.  It still doesn’t look like an omelette.  I have a lot of goals for 3.0, including providing a reusable documentation-viewing widget for other projects.  But one of the cool things I’ve been hacking on today is a combined location and search entry.  It’s still very much a work in progress, but I wanted to show screenshots anyway.

When you’re on a page, the location entry will show you what page you’re on, like so:

screen1

You can click the drop-down arrow for a history of where you’ve been:

screen2

If you click in the text field, you can type in some search terms:

screen3

And when you activate a search, it becomes a location in your history:

screen4

It still needs some polish, and I need some icons so I don’t have to abuse the search folder icon.  And it definitely needs some usability testing to see if its functionality is discoverable.  Help viewers can’t afford to have a learning curve.  But it’s been fun to play with so far.

Creative Commons Attribution 3.0 United States
This work by Shaun McCance is licensed under a Creative Commons Attribution 3.0 United States.