Apple Guide FAQ | Deciding Whether to Use Mixins

What is a mixin?
How do I decide whether to use mixins?
How do I set up and compile a mixin?
How do I control when a mixin mixes into the parent guide?
How do I use elements from the parent guide in a mixin?
Why does GuideMaker refuse to compile my mixin?
Why won't a mixin mix into the parent guide?
Why does the guide look strange when a mixin is active?

How do I decide whether to use mixins?

It's more complicated to code and maintain both a parent guide and a mixin than to maintain just a single guide, so the choice of whether to use a mixin or simply include the content in the parent guide can be a complex one. Mixins are particularly suitable for isolating volatile content, shipping updates to an existing guide, and managing complex configuration issues.

If you have content that changes more often than the rest of the guide, you can create a mixin to contain just that content. The mixin can then be updated without updating the entire guide file.

If you have an existing guide that only needs additions and minor changes, creating a mixin may be simpler than updating the entire guide. Users who download the upgrade need only download the changed material in the mixin. (If you are replacing a lot of the content, however, it's probably better to update the guide itself rather than use a mixin.)

If you want to present instructions that depend on the user's configuration, you can place the sequences for each configuration in a separate mixin. Then you can embed an appropriate qualifier resource in each mixin. The qualifiers should be mutually exclusive, so that for each possible configuration, exactly one qualifier returns true. This ensures that only the appropriate mixin is used when the user opens the parent guide.

How do I set up and compile a mixin?