zensical-docs skills started

docs/skills/zensical-docs/references/discoverability-and-ia.md

@@ -0,0 +1,74 @@
+# Discoverability and Information Architecture
+
+Use this reference to design docs that are progressively discoverable from overview to implementation detail.
+
+## IA Model
+
+Organize by user intent, then by product area.
+
+Recommended top-level model:
+
+1. Learn (concepts, architecture, mental models)
+2. Do (task/how-to paths)
+3. Reference (API, config, command catalog)
+4. Troubleshoot (symptoms, diagnostics, fixes)
+
+References:
+- Diataxis framework: https://diataxis.fr/
+- Divio documentation system: https://documentation.divio.com/
+
+## Progressive Discoverability Pattern
+
+### Layer 1: Section Overview
+
+Each section starts with an index page containing:
+
+- What this section is for
+- Who should read it
+- Common journeys
+- Links to key tasks and references
+
+### Layer 2: Task or Concept Pages
+
+Each page includes:
+
+- 1-2 sentence purpose
+- prerequisites
+- internal links to references and next steps
+
+### Layer 3: Deep Reference
+
+Keep deep details in dedicated reference pages and link to them from task pages when needed.
+
+## Navigation Design Rules
+
+1. Keep navigation labels user-facing and action-oriented.
+2. Avoid duplicate labels in separate branches.
+3. Place high-frequency tasks near the top.
+4. Keep section depth shallow where possible.
+
+Relevant Zensical configuration docs:
+- Navigation: https://zensical.org/docs/setup/navigation/
+- Search: https://zensical.org/docs/setup/search/
+- Header: https://zensical.org/docs/setup/header/
+- Footer: https://zensical.org/docs/setup/footer/
+
+## Link Strategy
+
+- Every deep page should have at least one inbound link from a higher-level index page.
+- Add "See also" blocks for neighboring tasks.
+- Link to source-of-truth reference pages instead of duplicating config tables.
+
+## Search Optimization for Docs
+
+- Put key terms in title and first paragraph.
+- Use specific H2/H3 headings that match user query language.
+- Keep repeated boilerplate minimal so snippets stay informative.
+
+## Review Heuristics
+
+A documentation journey is healthy when:
+
+- users can identify their path within 10 seconds on a section index page
+- users can complete primary tasks without opening more than 2-3 tabs
+- users can recover from common errors without external support tickets