Skip to main content

Taxonomies

The more information you have, the harder it is to find things. Markdown enables you to tag content, but without any checking for consistency. DocStatic enables you to apply an information architecture to your content with taxonomies.

Designing an information architecture​

It's beyond the scope of this document to cover information architecture in great depth, but here are some suggestions:

  • Limit your hierarchy to three levels. This maps well to traditional indexing.
  • Normalize your terms. Prefer plurals over singulars or verbs. Prefer single words over phrases.
  • Spell out acronyms and abbreviations.
  • Try to limit the top-level to ten categories.
  • Try to limit the mid-level to seven categories.
  • Use as many leaf-level categories as required.

Applying a hierarchy to flat tag systems​

Ideally, you should apply the information architecture to all your information platforms (bug-tracking systems, wikis and so on). This means that tags have to meet the most restrictive criteria:

  • Tags must contain their own parent categories, separated by an underscore ( _ ).
  • Lowercase letters only. No numerals, spaces (use a hyphen instead) or special characters.

To prevent the tags becoming unreasonably long, nesting is limited to a maximum depth of three levels. In some cases, this requires flattening the structure. For example, while regions_europe_uk_scotland is logical, it has four levels and so must be structured as regions_uk_scotland.

Managing taxonomy tags​

When tagging content in the CMS, you are limited to the set of tags that you define.

  1. Select Taxonomies from the collections and Add a taxonomy.
  2. Add any mid-level child tags. These should include the parent tag (parent_child).
  3. Add any leaf-level child tags. These should include the parent tag (top_mid_leaf).
Note

You don't have to include the parent and an underscore in a child tag, but if you leave them out then you'll be presented with a flat list of tags when you add a tag to a topic.

Tagging content​

In the CMS when editing a topic you can either use Search Mode to search for a term or select it from the Tree View. When you add a tag, all parent tags are added automatically. However, only one instance of each tag is added.

Tip

Avoid tagging content outside the CMS. This will keep your tags consistent and make searching for content easier.

Related topics

  • Taxonomy tags – Using taxonomy tags in DocStaric
  • Head metadata – Declaring page-specific head metadata through MDX.
  • Related Topics – Automatically generate links to related content based on shared taxonomy tags.
  • Conditional text – Filtering content with conditional text settings.