GUADEC Documentation Workshop

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

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.

Yelp's Bookmarks Menu

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.

Add Bookmark Icon in the Location Entry

And taking a cue from Epiphany, the history and quick-search drop-downs show you which pages you’ve already bookmarked.

Bookmarked Entries in Quick Search

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

GIO docs in Mallard in Yelp
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.

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