Keys can provide a huge benefit but also create great complications. Here are some tips that may help to reduce some of the latter.
When setting up a project, remember to use the Keyspace Manager to register a keyspace for the root map. Do not register keyspaces for the submaps (unless those are used as a “root map” for other deliverables); only the root map’s keyspace is used for resolving keys.
If your key definitions are not in the root map, but in one or more submaps, be sure to use the special DITA-FMx “fmx-root-map” othermeta flag to reference the root map from the submaps. This feature (along with use of the Keyspace Generation feature) ensures that any edits to the key definitions will be automatically included in the keyspace.
When creating a map, go ahead and assign a key to each of the significant topicrefs. They may not get used, but may provide an easy way to reference those topics. This is especially useful for references if each command or function has its own key.
It doesn’t matter where keys are defined in a map. Some conventions will have them at the “top” of a map, but this is not necessary. The only thing to keep in mind is that if you have multiple instances of the same key, the first one (in document order) wins.
Rather than cluttering up your root map or submaps used to define topicref hierarchy, consider adding keydef elements to a “keymap.” This is not a map element type, but rather a map that you use to store key definitions. You can then reference this keymap from your root map using a mapref element. Add the mapref element to your frontmatter or other top-level container.
A “key element reference” is defined by element content contained within the topicmeta in a keydef in a map (or by a keyref to a glossary entry). Insert a keydef and provide the key name; the referenced file is not required if you are creating a key element reference. After inserting the keydef add a topicmeta element then a nested keywords element and a keyword element. The content of the key element reference will be taken from the keyword element within the keydef’s topicmeta.
Assign filtering attributes to the keyword elements to change the value of the resulting key element reference based on the use of different ditaval files.