Shaun's Blog

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="http://www.w3.org/ns/ttml">
    <tt:body>
      <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
        color</tt:span></em>.</tt:p>
      </tt:div>
      <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>
      </tt:div>
    </tt:body>
  </tt:tt>
</media>

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 projectmallard.org. 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.

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="http://projectmallard.org/experimental/">
    <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>
  </e:captions>
</media>

End result (very much a work in progress):

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.

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