Taxonomy

Taxonomy is the system of classification applied to content: the rules that determine how pages are named, typed, and tagged. This document defines the taxonomy for the entire portfolio site.

Content types

Every page on this site has a content type. Content type determines the page's purpose, structure, and the reader's expectation when they arrive.

Type	Purpose	Structure	Pages	Examples
overview	Orient the reader to a section	Short intro, links to sub-pages, key context	12	Section landing pages
guide	Walk the reader through a task	Before you begin → steps → Next step	18	User guide, admin guide
reference	Support lookup, not reading	Tables, definitions, code samples	24	API reference, taxonomy, KB articles
concept	Explain what something is or why it exists	Problem → explanation → implication	4	NimbusWiz overview, design decisions, insights
walkthrough	Annotate a system or process with rationale	What it's → how it works → why these choices	6	CI/CD pipeline, Vale style guide, dashboards
case-study	Document an experiment or project with findings	Question → approach → outcome → lessons	7	RAG experiment, writing for AI, AI feature doc plan

How each type constrains the writer

Each type creates a different structural expectation. A page typed guide must have a "Before you begin" section and a "Next step" link. A page typed reference must use tables for its primary content, not prose. These constraints are what make content types useful: they prevent the writer from defaulting to narrative when the reader needs something else.

The distinction between walkthrough and case-study is temporal. A walkthrough describes a system as it exists now (the CI/CD pipeline, the Vale rules, the dashboard structure). A case study describes something that happened: an experiment, a project, a process that produced findings. Walkthroughs answer "how does this work?" Case studies answer "what did you try and what happened?"

Type distribution

The current distribution across 71 pages:

Type	Count	Share
reference	24	34%
guide	18	25%
overview	12	17%
case-study	7	10%
walkthrough	6	8%
concept	4	6%

No single type exceeds 34%. If any type grows beyond 40% of the corpus, that's a signal to re-evaluate whether the type is too broad and should be split.

Controlled vocabulary

The following terms are used consistently across all pages. Variations and synonyms are listed where they exist, but don't use them in headings, labels, or navigation.

NimbusWiz product terms

Preferred term	Don't use	Definition
Modernization Advisor	Advisor, recommendation engine	The AI-driven feature that recommends upgrade paths
Quirk Intelligence	Quirk engine, quirk system	The behavioral pattern learning capability
Flight Profile	User profile, intent layer	The user-defined operational intent setting
Simulation Mode	Dry run, preview mode, sandbox	The pre-upgrade metric projection feature
system	fleet asset, legacy system, device	A registered Nimbus2000-class system in NimbusWiz
upgrade profile	upgrade plan, modernization plan	A named configuration applied during modernization

Documentation terms

Preferred term	Don't use	Definition
user guide	user manual, end-user docs, help	Task-based documentation for end users
admin guide	administrator guide, ops guide	Setup and configuration documentation for admins
knowledge base	FAQ, help centre, support docs	Self-service articles for common questions
API reference	API docs, developer docs, endpoints	Technical reference for the NimbusWiz API
step	action, instruction, task	A single action within a procedure
prerequisite	requirement, before you begin	A condition that must be met before a procedure

UI element naming conventions

Consistent with NimbusWiz UI copy throughout:

Element	Naming convention	Example
Buttons	Verb + noun (imperative)	Register system, Run scan, Apply profile
Section headings	Noun phrase, title case	System Assessment, Modernization Advisor
Field labels	Noun or noun phrase, sentence case	System name, Upgrade profile, Stability score
Status labels	Past participle or adjective	Completed, In progress, Failed, At risk
Error messages	Plain language, specific cause	"Scan failed: connection timeout. Check network settings."

Metadata model

Every page uses frontmatter to declare its metadata. All five fields below are completed on every page before it's published.

Required frontmatter

title: Page title           # Used in browser tab and OG tags
sidebar_label: Short label   # Used in sidebar (shorter than title if needed)
description: One sentence    # Used in search results and OG description
content_type: guide          # overview | guide | reference | concept | walkthrough | case-study
audience: devops-engineer    # devops-engineer | system-admin | technical-manager | all
tags:
  - nimbuswiz
  - api

Optional frontmatter

last_update:
  date: 2026-04-10

Tag taxonomy

Tags are lowercase, hyphenated, and drawn from this controlled list.

Topic tags: nimbuswiz, api, cicd, ia, taxonomy, ux-writing, analytics, ai, prompt-engineering, docs-as-code, vale

Audience values (one per page, set in the audience field): devops-engineer, system-admin, technical-manager, all

Tags are topic-based only. Content type and audience are separate frontmatter fields, not tags. This avoids duplication between the content_type field and the tag list.

Labeling conventions

Sidebar label rules:

• Use sentence case: Docs site structure, not Docs Site Structure
• Keep labels under 30 characters where possible
• Match the page's h1 heading (abbreviated if needed)
• Use "&" not "and" in sidebar labels only (space constraint)

Heading hierarchy

Level	Use	Convention
h1	Page title	One per page, matches title frontmatter
h2	Major sections	Sentence case, describes the content below
h3	Sub-sections	Sentence case, more specific than h2
h4	Rarely used	Only when h3 needs subdivision

No skipping levels or using bold text as a pseudo-heading.

Link text

• Descriptive, not generic: "Read the taxonomy", not "Click here"
• Matches the destination page's h1 where possible
• No URLs as link text