I just blogged about Mallard+TTML. And earlier I blogged about XML translations with ITS.

One of the nice features of ITS Tool is that it can merge ITS definitions from multiple sources. So when you embed TTML into Mallard, you don’t need to have a specific Mallard+TTML mode. Instead, the Mallard ITS definitions get applied, and the TTML ITS definitions get applied on top of them. I just added this ITS file to itstool git:

  <its:withinTextRule withinText="yes" selector="//tt:p//*"/>

This ensures that inline markup like tt:span doesn’t get split off with a placeholder into a separate translation unit. This one file applies the ITS definitions whether your TTML is embedded in Mallard, DocBook, XHTML, or any other format, or even if you have a standalone TTML file.

Mallard+TTML Video Captions

I said, “Why not add some simple captions to Mallard?” Philip said “Why not embed an existing format, like TTML?” Philip was so right.

<media type="video" mime="application/ogg" src="figures/gnotravex-video.ogv">
  <p>Simple demonstration of a game</p>
  <tt:tt xmlns:tt="">
      <tt:div begin="1s" end="7s">
        <tt:p>Drag pieces from the right to the left, making sure that
        adjacent edges have the same number<em><tt:span begin="1s"> and
      <tt:div begin="6.5s" end="14s">
        <tt:p>Press <keyseq><key>Ctrl</key>arrow keys</keyseq>
        to move all the placed pieces at once.</tt:p>

A nice bonus feature is the tt:span element. One second after the first caption is displayed, some extra text appears inside it.

We should host a TTML profile for Mallard+TTML on Authors concerned with interchange would then be able to specify that profile using ttp:profile to prevent non-Mallard TTML processors from choking up on the inline Mallard syntax.

Mallard Video Captions

The documentation team has recently started creating short videos to supplement our text help. The first video we shipped was for Tetravex, showing basic piece movement. The nice thing about this video is that it doesn’t include any UI elements with translatable text, so translators don’t have to go through the truoble of retaking it. It also has no audio, so there’s nothing to retake there.

But parts of the video could be helped by some explanations. For that reason, I started working on a media subtitling system for Mallard. The subtitles are written directly in your Mallard document, where they’ll get translated along with the rest of the document. They’re then inserted into the HTML and dynamically shown and hidden as the video plays.

Sample XML:

<media type="video" mime="application/ogg" src="figures/gnotravex-video.ogv">
  <p>Simple demonstration of a game</p>
  <e:captions xmlns:e="">
    <e:caption start="1" end="7">Drag pieces from the right to the left, making                                              
    sure that adjacent edges have the same number and color.</e:caption>
    <e:caption start="7" end="14">Press <keyseq><key>Ctrl</key>arrow keys</keyseq>                                           
    to move all the placed pieces at once.</e:caption>

End result (very much a work in progress):

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.

Faceted Navigation

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.

Mallard and SVG

I just wrote a short tutorial on how to embed SVG in Mallard. Because Mallard is designed well, you can easily mix other XML vocabularies into it. That means that simple SVG in Mallard wasn’t a good enough challenge. So I made it so that embedded SVG can use Mallard’s linking mechanism. With a bit more work, we could probably even dynamically generate text labels in SVG from Mallard page titles. And that could be the framework for some nice charts and diagrams.

Mallard Helping You Help Users in Need

I recently blogged about how you can help users in need.  My advice was completely independant of what tools you use to write, build, and distribute your help.  Whether you do all your help in a wiki or have static HTML on the web that you keep in a version control system or install DocBook files along with your software, I think what I wrote is a good way to handle user problems.

But I think Mallard can substantially help you do this more efficiently.  Mallard takes a very flexible approach to topic-oriented help that allows you to write new content easily.  If you’re writing linear documentation in a format like DocBook, it can be difficult to start writing a solution to a problem without first going through the arduous task of figuring out how it fits into the navigational structure.

If you’re using Mallard, you can just write a stand-alone page and publish it for review.  I recommend first deciding what kind of content you’re writing.  Is it a set of steps to accomplish a task?  A solution to a common problem?  A conceptual overview?  A tip to help the user work smarter?

Mallard doesn’t enforce this content type like DITA does, but knowing what kind of content you’re writing allows you to work from standard templates, which should help you write more useful content.  By the way, I recommend all projects identify common content types and produce templates for them.  This is something we’ll be tackling in the Gnome documentation team soon, and I invite everybody to build on our work.

Once you know what you’re writing, and with template in hand, you can more easily get down to the business of turning thoughts into words.  You can convert your page to HTML without plugging it into a larger document so that your user can review it on its own.

Of course, you’ll still need to get it integrated into a document if you want it to be useful to others.  This isn’t necessarily trivial.  It could be that you can just plug it into an existing guide for common problems.  But you very well may need to rethink parts of your content organization.  Mallard makes content organization easier and more flexible, but there is still no substitute for human thought.

The real boon is that you can help and engage your user before you get bogged down in bookkeeping.  And that helps you create a more dynamic community that can more effectively help its users.

♫NP: Brown Skin by India.Arie

Documentation From 6000 Miles

A lot of exciting things have been happening in the Gnome documenation world. One of the most exciting things to me is that much of the excitement is being driven by people other than me. For the last three weeks, my wife and I have been away on the Great American Road Trip. While we were gone, my team continued rocking. I’ve been pleasantly surprised to see people taking ownership, and absolutely delighted to see Mallard uptake.

Since I’ve been on the road, I haven’t had a chance to write much more than 140-character dents.  I need to  get back into the habit of writing daily, so I’m writing about the documentation-related topics that have rattled in my brain for the last 6000 miles.

(Note, if your aggregator strips images, you’re missing half the fun.  Clicky.)

Writing Open Source


Back in June, I attended the first ever Writing Open Source conference.  Thanks to some genorous help from the Gnome Foundation, four members of the Gnome documentation team were able to attend.  Meeting face-to-face in an atmosphere devoted to documentation allowed us to come together as a tightly knit team.  As I said, what’s exciting to me is that I’m not the only person driving things forward, and I really believe that’s due in large part to this event.

It wasn’t just Gnome folks, though.  We met people from various teams and shared our experiences and problems.  There is a lot we can learn from the greater open source documentation community, and a lot we can share with them.  The group has turned into a real community that is undertaking a number of shared initiatives.  If you’re interested in free software and free documentation, please get involved.

Thanks to the conference, I’m now in touch with Jim Campbell of the XFCE documentation team.  And through Jim, I’m in touch with Richard Johnson of the KDE documentation team.  I hope we can get some collaboration brewing.



About four years ago, I got the idea in my head that we’re going about documenation in entirely the wrong way.  We write long user manuals that assume users will sit down and read.  That just doesn’t happen.  So I set about doing what any documentation tool developer would do: crafting a system to address the issues I’d encountered.

It took four long years, during which time words like “vaporware” started getting thrown around, but my experiences in those four years helped me turn Mallard from a hare-brained idea into something I believe is a viable documentation platform.  There is now experimental Mallard support in Yelp, and people are banging hard on it.

The feedback so far has been mostly positive, along with some valuable constructive criticism.  I’ve tried very hard to create a system that is easy for writers, translators, and distributors.  As an upstream project that often sees heavy modification by our distributors, we face some fairly unique challenges, and Mallard address some of those challenges in new and innovative ways.



Gnome documentation has traditionally been licensed under the GFDL.  This was certainly a natural choice over a decade ago, but it’s become evident that the GFDL doesn’t suit our needs for various reasons.  This issue has been festering in our community for nearly as long as I have.

With the help of our own beloved almost-a-lawyer Luis Villa, our team has looked at our options and decided to use CC-BY-SA 3.0 for all future work.  Not only does the Creative Commons license suit the needs of our community better, it’s also being adopted by the Ubuntu and Fedora documentation teams, which can help foster collaboration between our communities.  Furthermore, it puts us smack in the middle of an amazing Free Culture movement.

Fun Ahead


There are far more exciting things happening in the Gnome documentation community than I have gimmicky road trip images for.  Paul, Phil, and Milo have been amazing in revitalizing our team.  If you’re interested in documentation, or if you’re looking for a way to get involved with Gnome, or if you just like road trip pictures, join us.  Subscribe to gnome-doc-list or point your IRC client to the #docs channel on

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