Traffic Management KB

KB-Conventions

2 min read

Knowledge Base Conventions

Guidelines for maintaining this Traffic Management knowledge base.

Structure

FilePurpose
README.mdConceptual overview, project description
index.mdNavigation hub, quick links to all pages

Index Organization

The index uses minimal top-level sections (Core, Reference, Tools) to keep the VSCode Outline view clean and scannable. Avoid adding more sections — consolidate instead.

Browsing

We use VSCode in the web to browse notes.

Open the KB:

https://github.dev/AgenticIntelligence/Traffic_KB

Quick Access

Replace .com with .dev in any GitHub URL to open in VSCode web.

Navigation tips:

  • Open Outline view in Explorer panel for document structure
  • Use Ctrl+P to quick-open files by name
  • Use Ctrl+Shift+F to search across all files

Core Principles

Brevity First

  • Bullet points over prose
  • One concept per line
  • If it takes a paragraph, it’s too long
  • Authoritative sources over internal rewrites
  • Link to Waka Kotahi, WorkSafe, legislation.govt.nz
  • Our job: summarize and point, not republish

Flag Time-Sensitive Info

  • Deadlines, transition dates, policy changes
  • Use format: (as of Dec 2025) or (deadline: July 2026)

Formatting

Callout Types

Use callouts sparingly for emphasis:

> [!info] Title
> 
> Neutral information, definitions
 
> [!warning] Title
> 
> Deadlines, deprecations, gotchas
 
> [!tip] Title
> 
> Practical advice, shortcuts

Acronym Definitions

Use #acronym to mark acronym definitions, to allow searching and indexing.

Define acronyms inline using this pattern:

> [!info] TMP #acronym
> 
> **Traffic Management Plan** — Site-specific safety document for road disruptions.
  • Place near first use in each page
  • Always include #acronym tag
  • Find all acronyms by searching for #acronym or via acronym index

Use [[page-name]] to cross-reference related topics. This enables:

  • Navigation between related concepts
  • Discoverability via Obsidian graph view

What NOT to Include

  • Full regulatory text (link to source instead)
  • Step-by-step tutorials (link to official guides)
  • Information easily found via web search
  • Opinions or interpretations without citations

Graph View

Backlinks