Five GUADEC Questions
2010-06-11
1) Who are you and what do you do?
I am Shaun McCance, GNOME Documentation Team Fearless Leader, maintainer of Yelp, and creator of Mallard. I’ve dipped my toe into just about every piece of the GNOME stack, but at the end of the day, I’m always the guy calling out for better help.
2) How did you get into GNOME?
Way back in 2003, the previous Yelp maintainer sent an email asking for help with Yelp’s XSLT transformations. I’d been wanting to get involved for some time, and it was something I knew how to do, so I jumped at the opportunity. I took over Yelp shortly after that.
A few months later, John Fleck, the previous documentation team lead, decided to step down to pursue other things in life. (Click. Buy. Enjoy.) He nominated me to replace him, and I’ve been the go-to guy for documentation ever since.
3) Why are you coming to GUADEC?
To run the documentation workshop, of course! Seriously, GUADEC is an amazing event and a great chance to get face time with the names I see on IRC all day. I’ll be presenting during the main conference and during the Open Desktop Day in the pre-conference, as well as running the documentation workshop on Tuesday. Hopefully, GUADEC will be the extra push we need to get top-notch help in GNOME 3.
4) In 1 sentence, describe what your most favorite recent GNOME project has been. (Doesn’t have to be yours!)
Banshee rocks my world.
5) Will this be your first time visiting the Netherlands?
Yes.
Yelp and the DOM
2010-06-08
Xan just landed a patch to get the DOM node from a hit test result in WebKit. This allows Yelp to have meaningful link text for the “Read Later” feature I blogged about earlier. But it also opens the door to all sorts of nice features.
One of the nice things about working with source formats like Mallard and DocBook is that the HTML that gets fed to WebKit is very predictable. In fact, it’s completely under my control. So now, if you use a Mallard code block, Yelp can offer some extra goodness when you right-click:
And if the author was good enough to put the code block inside a listing element (as I have in this example), Yelp will even suggest a filename:
Little features like this make Yelp really pleasant for reading system documentation and programming guides.
Read It Later With Yelp
2010-06-03
A common use for tabs in web browsers is to set something aside to read it later. This is sometimes handy in help as well, but tabs are a very heavyweight thing for a help viewer. Instead, I created a “Read Later” list. You can right-click a link and select “Read Link Later”:
The “Read Later” list appears at the bottom of your window, showing you everything you’ve been wanting to read:
The list will have proper link text soon, just as soon as WebKitGTK+ gives me a DOM node for a hit test result. (Hint, hint, lovely WebKit peeps.)
This feels really natural to me. Just like bookmarks and quick search and everything else in Yelp 3, the “Read Later” list is per-document. So you won’t see that Gnumeric function reference you’ve been wanting to look over when you’re trying to figure out how to get Banshee to recognize your portable media player. And one of the really nice benefits over tabs is that you can close Yelp and come back to it later, and your list will still be there.
GUADEC Documentation Workshop
2010-05-20
Milo and I will be running an all-day documentation workshop during the GUADEC pre-conference on Tuesday, July 27th. This is an exciting opportunity for you to work on our documentation, take part in collaborative planning, and learn best practices from experienced documentation writers. This is an unstructured workshop with lots of one-on-one guidance. You do not have to attend all day. Come when you like and leave when you’re done.
The workshop addresses both user and developer documentation. We will have a list of topics for both. Choose a topic that interests you to plan, write, and review. Or bring in your own application or library to document. We will help you plan effective content, write clearly and concisely, and review what you’ve written to make sure it meets your audience’s needs.
Documentation is important to the success of a free software project. I hope you’ll join us and learn how you can provide better documentation.
Better Yelp Bookmarks
2010-05-12
Last week, I revamped Yelp’s bookmarks. Like most other things in Yelp 3, bookmarks are now handled per-document. So when you’re viewing the Empathy help, you don’t see a bunch of bookmarks for Banshee and Tomboy and Brasero. Bookmarks are stored with their title and page type, so we can show the page type icon. We also sort by the page type first, as we do for quick search.
In this screenshot, Add Bookmark is insensitive because I happen to be viewing the page “Empathy Instant Messenger”, which is already bookmarked. It doesn’t make sense to bookmark the same page twice. When you want to bookmark a page, you can either use the menu item, or you can use the icon embedded into the location entry.
And taking a cue from Epiphany, the history and quick-search drop-downs show you which pages you’ve already bookmarked.
I had to steal Epiphany’s icon for this and install it along with Yelp’s other icons. I was surprised to find that it isn’t a standard icon. I think more applications should mark your bookmarked items when searching.
Mallard API References
2010-05-04
GIO docs in Mallard in Yelp
This is the GIO API reference, generated by gtk-doc, converted to Mallard, and displayed in Yelp 3. Yelp is a surprisingly nice API documentation viewer.
Update: If you use Devhelp a lot, you probably use the Search tab to get to symbols quickly. We’ve got that covered. The quick search feature in Yelp lets you search as you type on page titles and descriptions.
If you type multiple words separated by spaces, Yelp ANDs them. This is really handy for narrowing the results without having to type a perfectly matched string.
Big Blue Button
2010-04-26
I was invited to demo Mallard at a DITA Help Subcommittee meeting. They hold their meetings with GoToMeeting, a conferencing and desktop-sharing tool. Unfortunately, GoToMeeting only supports Windows and Mac. That’s a problem for me, because the only thing on my desk is Fedora. I searched a bit and stumbled across BigBlueButton, an open source system with all the bells and whistles of the proprietary ones. The DITA folks were nice enough to use BigBlueButton to talk to me.
There are some quirks. Sometimes the audio is choppy or it drops out. People said my desktop was hard to read unless I massively upped the font size. Some of these issues may just be because we used the demo server, which apparently doesn’t have the best deployment. The BigBlueButton developers, however, were extremely helpful. And they’re actively working on the audio issues.
So even with the quirks, and even though I had to install Flash, using BigBlueButton was a really nice experience. It’s left me wanting something more whenever I have to do IRC meetings. IRC meetings are horribly low-bandwidth, especially for collaborative planning. If I could actually talk to people, and show them what Yelp is doing on my desktop, I think we could be a lot more productive. It’s not quite as good as face time, but it’s a lot better than IRC.
I wonder how we could make awesome collaborative tools like this available to our teams in Gnome. Could we run a BigBlueButton server? Is Flash a non-starter for that? What can Empathy do for us? I know I can have a voice chat and share my desktop with someone, but what about a group of someones? Thoughts?
Faceted Navigation
2010-04-26
Ever since Matthew Ellison’s talk at the WritersUA conference, I’ve been thinking a lot about faceted navigation. This is a navigational design where you narrow your focus based on certain criteria. A recent example I’ve encountered a lot lately is in searching for real estate. You can narrow your results by how many bedrooms or a price range. Car sales sites might let you narrow based on color or type of car.
What I always try to do with Mallard is make it as simple as possible to provide rich navigation to help users. It’s not enough to be able to slap some pages on the web; any wiki can do that. The goal is to create something that encourages writers to write and organize well.
I wanted to explore simple and Mallardesque ways of doing faceted navigation, but it just didn’t make sense for any of the application help documents we’ve been doing. Along came the HIG. Our usability experts want to create a new pattern library to augment our design guidelines, and I decided to explore how well Mallard would fit. This, I realized, was my chance to try faceted navigation.
In this simple example, there is one facet with three choices. This is all defined using a simple Mallard extension format in the page file. The topics then declare which facet items they’re relevant for. Deselect ‘Mobile’ and you’ll see this:
This is all very rough at the moment, but it’s interesting. To me, anyway. With enhancements like faceted navigation, I think Mallard would be an excellent base for some new topic-oriented developer guides, such as the following:
- UI Guidelines and Pattern Library
- UA Guidelines and Templates
- Accessibility Guidelines
- Hacking Intros and Howtos
I’m interested to hear people’s thoughts on this.
Yelp Editor Mode
2010-04-01
Phil asks, Phil gets. Yelp has an editor mode, which looks like this:
In editor mode, Yelp shows a revisioon banner along the top, as well as revision badges next to link boxes. It also shows editorial comments, though that’s not in this screenshot. Also notice the “Stub Page”. This comes from a file with the .page.stub extension, instead of the regular .page extension. This was an idea Phil had to help us stub out extension points in documents when we write them. Yelp only shows stub pages in editor mode, and it gives them a red background so you know they’re stubs:
And, by the way, this is no longer yelp-3-0. This is master.
Mental Telepathy
2010-03-30
When Jim Campbell and I presented Mallard at the WritersUA conference last week, we wanted to show off how easily you could drop a page into a directory and have it picked up by the dynamic linking system. So Jim created a help page for the (sadly fictitious) “Mental Telepathy” plugin for Empathy. We could just drag it into a folder and restart Yelp, and people would ooh and aah.
This page is too good not to share, so here’s a screenshot:
I hope to see this feature ready by 3.0.
