Mallard – Better Help for Better Software

Shaun McCance writes about Mallard, a new XML syntax for writing user documentation and help.


Mallard: Better Help for Better Software

Mallard is a beautifully simple system for producing topic-oriented help that can be easily extended by third parties. Although developed initially to meet the needs of the GNOME documentation team, its simple syntax and flexible design have made it an attractive solution for other documentation teams.

This article explains why Mallard was developed, what problems it solves, and where it’s heading.

A Short History

In the beginning, there was DocBook. DocBook is the long-standing champion of free software documentation systems, and it shows in the number of projects that use it. DocBook is a very general-purpose XML vocabulary, containing over 400 distinct elements for everything from bibliographies to synopses of classes and methods in object-oriented programming languages.

GNOME has used DocBook for user and developer documentation for as long as GNOME has provided documentation. Whereas most people convert DocBook to HTML or PDF for delivery, GNOME took the unique approach of installing the source DocBook files and viewing them through a specialized help viewer. This has allowed us to maintain a consistent style, and has paved the way for more dynamic presentations.

Over the years, as we tried to do more with our documentation, we began to encounter more and more problems. One of these problems was unique to upstream providers like GNOME: Our downstream distributors were modifying and extending GNOME, and they needed to update our documentation to match. As early as 2004, we began to think of ways we could make our documentation more extensible for our distributors.

We didn’t set out to create a new format. In fact, the earliest ideas involved extending DocBook in various ways to support dynamic content. But to accomplish what we needed, our DocBook wouldn’t really look like DocBook anymore. Plus, DocBook’s verbose and sometimes complex markup wasn’t helping our volunteer community and occasional contributors.

We needed something simpler, and something that allowed our downstream distributors to build on our content to help users. Mallard was born.

Introduction to Mallard

A Mallard document is a collection of pages. Each page stands on its own. This is different from traditional documentation formats, where a document is a linear sequence of chapters and sections. The idea is not new. Encyclopedias have been organized around self-contained topics for centuries. When the idea is applied to documentation, it’s called topic-oriented help. Users can read what they need without reading an entire manual.

Each Mallard page is stored as an XML file. The Mallard vocabulary contains just over 40 elements, culled from first-hand experience with free software documentation.

Here’s an example Mallard page file:

 <page xmlns="" id="types-ducks"> <title>Types of Ducks</title> <list> <item><p>Mallard</p></item> <item><p>Eurasian Wigeon</p></item> <item><p>Common Teal</p></item> </list> </page> 

A typical application help document will contain dozens of pages, each giving specific instructions or explaining a concept. So we can create more pages and link from one page to another. Here’s another page:

 <page xmlns="" id="ducks"> <title>Ducks</title> <p>For a list of types of ducks, see <link xref="types-ducks"/>.</p> </page> 

As in many other documentation languages, the link text is inserted automatically when the page is displayed. We could also add more content to these pages using Mallard’s built-in markup for common design elements like step lists, notes, and code listings.

A topic-oriented format alone makes it somewhat easier for downstream distributors to add content, but they still have to patch the upstream pages to link to their own content. We needed a way to dynamically insert pages into a document by just dropping some extra files into a directory.

The Power of the Duck Side

The big idea behind Mallard is dynamic links. Instead of embedding all links inside paragraphs, we can declare links and other metadata at the top of the page. The second page above could instead be written like this:

 <page xmlns="" type="guide" id="ducks"> <info> <link type="topic" xref="types-ducks"/> </info> <title>Ducks</title> </page> 

This is now a guide page. Guide pages are special types of pages that hold links to other pages and serve as the navigational glue of the document. When this page is displayed, it will be have a link to “Types of Ducks”. What’s more, “Types of Ducks” will have a link back to this page.

Links declared in the info section reciprocate. You don’t need to specify the link on both ends. It works automatically. This example, however, just lets topics know what guides they belong to. To add third-party content effectively, we need to insert links into guide pages.

So we turn it around. Instead of having a guide page link to its topics, we have topics link into their guides. Here’s another topic page:

 <page xmlns="" id="scientific-names"> <info> <link type="guide" xref="ducks"/> </info> <title>Scientific Names</title> <list> <item><p>Anas platyrhynchos</p></item> <item><p>Anas penelope</p></item> <item><p>Anas crecca</p></item> </list> </page> 

Instead of “Ducks” specifying a topic link to “Scientific Names”, we have “Scientific Names” specifying a guide link to “Ducks”. Guide links and topic links are converses. Whenever there is a guide link, there is a topic link going the other direction. So “Scientific Names” will appear on the “Ducks” page exactly as “Types of Ducks” does.

This simple solution allows us to create help with rich navigational structures that make sense to the reader. More importantly, it allows third parties to seamlessly integrate new content in places where users can actually find it. This means downstream distributors can make our help more useful by adding distribution-specific content. This is also a simple way to integrate plugin help for plugin-heavy applications like the GIMP.

Future Development

The Mallard 1.0 specification is still a draft, and Mallard continues to improve based on community feedback. Large changes are unlikely before 1.0 is declared final in July, but we have already discussed features that could be useful in future versions of Mallard.

One area where Mallard is likely to grow is dynamic link types. In addition to the guide and topic links discussed in this article, Mallard also features seealso and next links. Next links were added in direct response to community feedback to support linear series of pages. As Mallard is used for larger and more complex documents, we are likely to want other types of navigation. We’re also looking at ways to give writers better control over the grouping and presentation of links.

Every new feature, however, will be scrutinized for simplicity. Simplicity is as key to the design of Mallard as dynamic links. It’s what people like about Mallard. This means that we can’t add every piece of markup that might be useful to somebody.

Fortunately, Mallard can be extended. It was designed with modern XML best practices in mind, and it defines very rigidly how to add new markup from external namespaces. It does its best to ensure that extension elements can provide good fallback content.

One interesting idea for an extension came up as a result of discussions within the Ubuntu documentation team. Some people were worried about the lack of control over what packages can add content into a document. A possible solution is to define an extension that requires links to be cryptographically signed.

Other ideas for extensions include dynamic-content glossaries, simple charting functionality, sortable tables and lists, and automated review tracking. As people push Mallard in new directions, new ideas are bound to come up.

Learn More

To get started with Mallard, read the Ten Minute Tour. After that, read some of the other Mallard tutorials. The draft specification is easy to read, and is full of examples to help you understand how to use each element.

The beauty of free software is that you can always learn from what other people are doing. For real-world examples of Mallard, take a look at the help documents for Empathy, Calculator, Hamster, GBrainy, and Tetravex. Or look at the source for the web site, which is all written in Mallard.

If you’re interested in Mallard, please join the Mallard mailing list.

About the Author

Shaun McCance has over eight years of experience as a writer, programmer, and community leader. A well-known open source documentation leader, he spearheads the GNOME documentation team and maintains many of the programs that make GNOME documentation work. Shaun runs, a consulting company specializing in documentation tools and community documentation.

Discuss this story with other readers on the GNOME forums.

Posted on March 30, 2010, in March 2010. Bookmark the permalink. Leave a comment.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: