logo hsb.horse

Architecture Decision Record

Glossary introduction policy to separate blog posts and knowledge entries

Separate time-series posts in blog from long-lived reference content in glossary, with distinct URLs, collections, and index flows.

Accepted #content #glossary #blog #information-architecture #seo

Glossary introduction policy to separate blog posts and knowledge entries

Decision

  • Keep chronological posts (problem, investigation, solution) in blog.
  • Keep long-lived reference content such as definitions, spec notes, and comparison tables in glossary.
  • Add a new glossary collection and implement index/detail routes at /glossary and /{lang}/glossary.
  • Do not migrate existing blog entries immediately; apply this classification to new content first.

Context

Knowledge notes and blog posts are currently mixed in blog.
That makes both reader navigation and authoring rules ambiguous.

  • Blog posts: publication context and timeline matter
  • Knowledge entries: ongoing updates and reuse matter

With one collection, list UX, internal linking intent, and SEO intent become mixed.

Options

  • Option A: Keep everything in blog and separate only with tags.
  • Option B: Split into blog and glossary (chosen).
  • Option C: Split naming rules first and delay implementation changes.

Rationale

  • The reading model becomes explicit: timeline-oriented blog vs reference-oriented glossary.
  • Collection split allows future UI optimization per content type (sorting, filters, emphasis).
  • URL separation makes page intent clearer for search engines.

Consequences

  • Add a glossary collection schema in src/content.config.ts.
  • Create content/glossary/ and generate IDs with lang + slug.
  • Add static routes under src/pages/glossary/* and src/pages/[lang]/glossary*.
  • Add glossary copy in i18n dictionaries.
  • Migrate existing entries gradually; define redirect policy in a separate ADR if needed.