Mallard Training

2011-06-21

Mallard makes it easy to create dynamic, topic-oriented help documents, but even the simplest technologies have some learning curve, best practices, and advanced topics. To help developers and technical writers make the most of Mallard, I’m offering professional Mallard training services.

Mallard training starts with the basics: outlining a document, creating topics, and writing pages. You’ll explore Mallard’s unique linking and navigation system and learn how to create navigational structures that reflect what your readers are looking for. You’ll learn best practices on writing topics culled from years of in-the-trenches experience with Mallard and other documentation formats. All of this is done hands-on, creating actual documents from start to finish.

Training can be customized to your needs. You can also learn about topics such as using and developing Mallard extensions, integrating status tracking into your workflow, and working collaboratively with multiple contributors.

If you’re interested in Mallard, contact Syllogist for more information.

We’ve talked about doing run-time conditional processing in our help for a very long time, nearly as long as I’ve been around. When you have applications that can run in multiple environments, you sometimes need to write different help text for difference cases.

For example, take an instant messaging application like Empathy. In GNOME 3, the Telepathy integration means that users can chat directly from the tray. Hackers know it’s not actually Empathy, but users don’t care. It’s chat. In GNOME 2, you usually interact with Empathy through the notification tray. In Unity, it integrates with the messaging menu. These are all things we should write about in the help.

But it’s hard to write about things when you don’t know where your help is read. The only way to deal with this is to patch the help for different environments. My experience is that that rarely happens. Plus, you don’t always create different packages for different environments. The exact same Empathy package in Fedora is used in GNOME Shell, GNOME fallback, and XFCE.

Other XML formats have conditional processing, but their design isn’t suitable for our needs. They usually work by having a set of attributes that take some tags. The behavior isn’t usually specified, because it’s assumed that they’ll be handled by a vendor-specific build tool that strips things out before creating a deliverable. Our source format is our deliverable format, and we want to adapt it at run-time.

So I’ve just landed some changes in Yelp to support a Mallard extension format for run-time conditional processing. Any block element can have the if:test conditional attribute added. This is evaluated as an XPath expression with extension functions that can tell you things about the environment. This is much more flexible than a set of tagging attributes, because you can combine multiple tests with “and” and “or“.

<p if:test="if:env('gnome-shell')">This is only shown in GNOME Shell</p>
<p if:test="if:env('gnome-shell') or if:env('gnome-panel')">
  This is shown under GNOME Shell or GNOME Panel
</p>

The if:test attribute is a convenient short-hand syntax. There are also conditional processing elements that allow you to do basic branching and fallback.

<if:choose>
  <if:if test="if:env('unity')">
    <p>You're using Unity</p>
  </if>
  <if:if test="if:env('xfce')">
    <p>You're using XFCE</p>
  </if:if>
  <if:else>
    <p>You're using something else</p>
  </if:else>
</if:choose>

The full syntax has another advantage. What happens if you hand a document with conditional processing to a Mallard processor that doesn’t support it? It turns out that Mallard has very well-defined rules for how unknown extensions are handled. In the first case, you just have an external attribute on a known element. The attribute is ignored and the p element is processed as normal.

In the second case, you have an external element in a block context. A Mallard implementation that doesn’t do conditional processing will visit the children in restricted block context. In restricted block context, unknown external elements are ignored.

Yelp 3.0 doesn’t have the conditional processing support. The following two snippets will do what they say in Yelp 3.0, but they will be exactly equivalent to Yelp 3.2 with conditional processing support.

<p if:test="if:env('foo')">
  This will be displayed in Yelp 3.0
</p>
<if:choose>
  <if:if test="if:env('foo')">
    <p>This will not be displayed in Yelp 3.0</p>
  </if:test>
</if:choose>

Details are all subject to change, of course. This does basically follow a proposal I made to the Mallard mailing list last August. But for now, it’s in an experimental namespace. I just need to iron out the kinks and write up a specification on projectmallard.org.

Open Help Conference

GNOME 3

2011-04-07

I’ve never been more excited to be a GNOME developer. After years of hard work and planning, GNOME 3 was released yesterday. Check out the Introduction to GNOME from our brand-new help to learn all about it.

GNOME 3 shows the innovation that open source communities can bring. Hundreds of developers, designers, writers, testers, and translators worked hard to deliver an amazing new user experience. Among them are the fantastic people who helped create an all-new help system that rivals anything I’ve seen elsewhere. My release notes list Phil Bull, Jim Campbell, Tiffany Antapolski, Natalia Ruz Leiva, Shaun McCance, Paul Frields, Mike Hill, Aline Bessa, Marina Zhurakhinskaya, and Kelly Sinnott. If I missed anyone, I’m really sorry. It’s hard to keep track of so much awesome.

We tossed out the old manual (who reads those?) and started fresh with topic-oriented help, building on the dynamic Mallard language. The results are amazing. The initial release has 214 pages, carefully organized and cross-linked to help you find the information you need quickly and get back to your life. What is a workspace? Select files by pattern. Enter special characters.

Frederic Peters did amazing work on library.gnome.org so all the new help is available online. But remember that all of this is available from the Help application on your GNOME 3 desktop. The help viewer was completely rewritten for GNOME 3, and I think you’ll really like what we’ve done.

By the way, if you want to meet up and learn about GNOME’s fresh approach to help, you should come to the Open Help Conference this June. At least Phil, Jim, and I will be there, and we’ll be joined by documentation teams from other great open source projects.

We’re not done yet.

Help needs to constantly improve and evolve as we learn more about what our users need. The GNOME documentation team is already hard at work on more pages and revisions to existing pages. We’ll be pushing updates to the help weekly. If you want to get involved, subscribe to our mailing list and send an email to gnome-doc-list@gnome.org.

We also welcome drive-by contributions. One of the really nice things about topic-oriented documents with Mallard is that it’s easy to just write up a page about something without worrying about making revisions to an entire book. If you love using GNOME, a great way to contribute is by writing a short page about an awesome time-saving trick. We’ll put these under Tips & Tricks, and users worldwide will learn something cool because of you.

I am GNOME

Phil mentioned the future of Desktop Help, but he was sparse on details. Let me fill in the blanks. With Mallard, we worry mostly about structure and content, and we leave the rendering details to Yelp. Sometimes we want to influence the style, and for that we use Mallard’s style hints. But sometimes, just sometimes, for very special pages, we want to inject some pizzazz.

We can do that too. Watch:

This is using some custom style hints and a very small Mallard extension, which falls back gracefully thanks to Mallard’s well-defined rules for extensions and fallback.

This is still a work in progress. And with work continuing into the night at the help hackfest in Toronto, it’s very much in progress.

I blogged earlier this year about doing faceted navigation with Mallard. The idea sat dormant for a while, but with the new GNOME developer demos, I had a really fun use case.

Here’s the basic idea: Topic pages declare values for facets. These are basically just categorized tags. So my Message Board tutorial has some simple markup that says it’s written in C and it’s teaching you WebKit. You then have a page that collects all the topics and provides selectors to narrow what you’re looking at.

So as I browse the demos, I can say that I’m only interested in C. And perhaps I’m looking at GTK+ and Clutter to see which one is a better fit for a project I’m starting. I can uncheck everything else. Then I’m looking at only demos in C that teach either GTK+ or Clutter. Screencast:

All of the scripting is handled by Yelp. Document authors only need to write some simple declarative markup in a Mallard extension format.

(Aside: When I try to upload an ogv file to WordPress, it tells me the file type doesn’t meet security guidelines. If I rename it to ogg, I can upload it, but WordPress inserts it as audio. I have to write the HTML for the video by hand. Could somebody please make it easier to use Ogg Theora on blogs.gnome.org?)

Open Help Conference

Mallard+TTML+ITS

2010-11-08

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:rules
    xmlns:its="http://www.w3.org/2005/11/its"
    xmlns:tt="http://www.w3.org/ns/ttml"
    its:version="1.0">
  <its:withinTextRule withinText="yes" selector="//tt:p//*"/>
</its:rules>

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.

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):

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

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.