Design Principles

Mallard was designed to allow others to plug pages into your document. This allows distributors, OEMs, and plugin authors to better help users by providing the appropriate information where it belongs: integrated into the rest of the help. Unlike other formats that require static maps or a linear document structure, Mallard features unique automatic linking mechanisms that are designed to support adding new pages without modifying original content.

Writing help is hard enough without having to fight your help format. Rich semantic markup can be valuable, but only when it provides a clear benefit. Too much markup can overload writers, making them second-guess which elements they should be using.

In Mallard, there is just enough markup to convey common information. Every element in Mallard must serve a real purpose for most users. People who need more specific markup can use style hints or markup from external namespaces.

Furthermore, names of elements and attribute in Mallard should strike the right balance between being too verbose and being too cryptic. Very verbose element names make the markup difficult to read quickly. Cryptic element names are difficult to remember.

Anything that has to be declared multiple times creates a potential for incorrect or outdated information. This increases the workload for writers and editors, who have to sift through more data to ensure their documents are correct. A Mallard processor knows about all pages in a document, so information stored on one page can affect the display of another page.

Breaking free of linear navigation means topics can appear in multiple places, and users can navigate to them by the route that matches their own mental model. It also makes it easier to get lost in a document with no sense of context. Without contextual navigation, topics become isolated and readers can't explore.

The automatic linking features in Mallard help create navigational structures. The link types reflect how people expect to navigate documents, and new link types can be added. Because Mallard is extensible, developers are encouraged to explore innovative new ways of organizing and navigating topic-oriented documents.

Document translation is a difficult and painstaking process. Some formats make that process more difficult with features that don't work well with localization. Mallard has its roots in software that is translated into over 50 languages, and was designed to solve real problems faced by translators. See Internationalization and Localization for more information.

Many formats are designed to be converted into a deliverable format by a build process that's run infrequently. The automatic linking mechanisms employed by Mallard assume that Mallard is the delivery format, so processing speed is important. Furthermore, with collaborative writing and editing iterations, it's important that contributors can see the results of their work quickly.

Mallard strives to be as simple as possible while providing a powerful framework for pluggable, topic-oriented documents. It cannot be all things to all people without being overloaded with hundreds of elements nobody can remember. At the same time, a well-designed XML format can serve as the foundation for innovation.

The schema that defines Mallard allows elements and attributes from external namespaces to be used in most places. The processing expectations for these depends on context, and is designed to allow extensions with graceful fallback behavior. This allows new features to be developed to serve specific needs without the core of Mallard becoming cumbersome.