Skip to main content

Hub Index Template

How to Apply This Template​

Do not rewrite the index until Phase 2 is complete.

Phase 1 — Audit (read-only)​

  1. Read the existing index in full.
  2. List every content chunk. For each, answer:
    • Is this orientation/routing? → keep in index.
    • Is this teaching/detail already in a child page? → grep to confirm, mark safe-to-drop.
    • Is this teaching/detail unique to this index? → it needs a child home. Name it now.
  3. Stop. Do not write anything until every unique chunk has a named destination.

Phase 2 — Relocate (write to children only)​

  1. For each unique chunk: move it into the right child page (or create a new child). Adapt headings to fit. Confirm the child reads coherently after the addition.
  2. Run grep -r "key phrase from chunk" docs/ to confirm it now exists in the child.
  3. Do not touch the index file yet.

Phase 3 — Rewrite index​

  1. Now apply the template. Strip teaching content — it has a home.
  2. Verify: body ≤ ~30 lines, every child appears once with scent, Zoom Out complete.
  3. Run grep -r "key phrase from stripped content" docs/ — must return at least one hit in a child page for each stripped unique chunk.

SECTION-TITLE

SECTION-MANTRA: One sentence a newcomer gets — what this section is for and why you'd care.

The Spine​

  1. Child A — the reason to open it (the payoff, not a label)
  2. Child B — …
  3. Child C — …

Zoom Out​

Purpose​

A hub page orients a section — what it covers, entry paths, core links. It does not teach. See Page Types for the full page-type catalogue.

Grounding​

Three converging sources establish why the hub must stay lean.

Information scent (Nielsen Norman / information-foraging theory). Every link must let the reader predict what they will find behind it. A hub that teaches rather than routes destroys scent: the reader cannot tell which door leads to the answer they need.

Hick's Law. One ranked path beats a flat catalog. Every additional unchosen option costs decision time. A hub that lists everything equally routes no one.

Diátaxis. A hub orients; it does not explain. Explanation belongs in child pages. Mixing the two produces pages that neither orient well nor explain well.

The Teacher's Shadow (Teacher archetype). The Teacher's job is compression and ignition — hand the reader a map and a reason to use it. The Teacher's named shadow is over-explaining: giving the learner everything so they build nothing. An index that contains all the teaching is shelf furniture — a map nobody needs to open because the territory is already there.

The Feynman gate. If you cannot compress the section's purpose to one sentence, compression is unfinished. The opener is that sentence.

The Seven Rules​

  1. Body ≤ ~30 lines. If it needs more, that content belongs in a child page, not the index.
  2. Every child appears exactly once, ranked. Sequence where reading order exists; importance or grouping where it doesn't. No flat alphabetical dumps. No orphans, no duplicates.
  3. Each Spine line carries scent. A reason to open the link — the payoff, not a dry label. Test: would anyone open this door?
  4. One-sentence opener. If it can't compress to one sentence, the section isn't understood yet (Feynman gate).
  5. No teaching in the index. Explanation lives in the child page (Diátaxis: orientation ≠ explanation).
  6. Mobile-first. Bold-label + dash, never layout tables. (WCAG 2.1 SC 1.4.10 — content must reflow at 320px.)
  7. No "Also Here" catalog block. Fold everything into the ranked Spine. A separate dump is the Teacher's Shadow made structural.

Before → After Example​

Before (bloated — 47 lines)​

---
title: Questions
tags: [Questions, Problem Solving]
---

Questions are the engine of learning. Socrates believed that the unexamined life is not worth
living. Modern cognitive science agrees — questions activate prior knowledge, direct attention,
and produce deeper encoding than passive reading. The right question at the right time can unlock
an entire domain.

There are many types of questions. Convergent questions narrow options toward a single answer.
Divergent questions open possibility space. Clarifying questions reduce ambiguity. Probing
questions surface assumptions. Meta-questions examine the question itself.

The questioning system here includes...

## Tools

- [Questions Database](/docs/)
- [Questioning System](/docs/)
- [Socratic Method](/docs/)
- [Problem Solving](/docs/)
- [Decision Making](/docs/)
- [Mental Models](/docs/)

## Why Questions Matter

[Three more paragraphs explaining epistemology and pedagogy…]

## Also Here

- [Debate Frameworks](/docs/)
- [First Principles Reasoning](/docs/)

After (lean — 14 lines)​

---
title: Questions
description: "The tools that turn confusion into a solvable problem — before you pick a solution."
type: hub
loop_phase: action
level: entry
tags: [Questions, Problem Solving]
---

Questions come before answers — the right one surfaces the real problem.

## The Spine

1. **[Questioning System](/docs/)** — a framework for choosing which type of question to ask, when
2. **[Questions Database](/docs/)** — a library of prompts by domain and phase
3. **[Socratic Method](/docs/)** — how to turn a question into a self-correcting loop
4. **[Problem Solving](/docs/)** — where to go when the question is sharp but the path isn't

## Zoom Out

- **Up:** [Navigation](/docs/navigation/) — the three systems that direct action
- **Next:** [Decision Making](/docs/systems/problem-solving/decision-making/) — what to do when the question is answered

What changed: 47 lines → 14. The epistemology went to the child pages where it belongs. The opener compresses the section's purpose in one sentence. Every link carries a payoff, not a label. The "Also Here" dump was folded into the ranked Spine.

Context​

  • Page Types — full page-type catalogue and when to use each
  • IA Standard — placement bands, folder-as-function, depth ≤ 4
  • Players Template — sibling template for industry players pages
  • Teacher Archetype — the compression and ignition mandate; the Shadow this template guards against