Enhance specs index with reading order and cross-references

[dimitri-yatsenko]

Summary

Enhances the reference specifications index with clear reading order, prerequisites, and cross-references to related documentation.

Problem

From cohesion review (COHESION-REVIEW.md Issue #7, Medium Priority):

• Users don't understand relationships between specs
• No guidance on which spec to read first
• Missing links to related how-to guides and explanations
• Users reading semantic-matching.md don't know it connects to model-relationships.ipynb

Solution

Comprehensive enhancement of reference/specs/index.md:

1. How to Use These Specifications

Three user personas:

• New users → Start with tutorials/how-tos
• Implementers → Use specs as authoritative sources
• Debuggers → Clarify ambiguous behavior

2. Reading Order Section

Foundation (Start Here):

1. Table Declaration
2. Primary Keys
3. Type System

Then branch based on needs:

• Working with data? → Data Operations
• Building queries? → Query Algebra
• Using large data? → Object Storage

Each path shows:

• Prerequisites (what to read first)
• Numbered sequence
• Explicit progression

3. Enhanced Specification Tables

New columns:

• Prerequisites: Shows dependencies (e.g., "Table Declaration, Primary Keys")
• Related How-To: Links to practical guides
• Related Explanation: Links to conceptual docs

Key concepts summary: Brief overview of main topics for each category

4. Complete Cross-References

15+ how-to guide links:

• Define Tables, Query Data, Insert Data, Run Computations, etc.

10+ explanation links:

• Relational Workflow Model, Query Algebra, Type System, etc.

All prerequisites documented:

• Clear dependency chain prevents confusion

Example Enhancement

Before (Simple List)

| [Query Operators](query-algebra.md) | Operators: restrict, proj, join... |

After (Rich Context)

| Specification | Prerequisites | Related How-To | Related Explanation |
|---------------|---------------|----------------|---------------------|
| [Query Operators](query-algebra.md) | Table Declaration, Primary Keys | [Query Data](../../how-to/query-data.md) | [Query Algebra](../../explanation/query-algebra.md) |

Plus key concepts: Restriction (&, -), projection, join, aggregation, universal set

User Impact

Before (Confusion)

• "Which spec should I read first?"
• "What do I need to know before reading semantic-matching.md?"
• "Where's the practical guide for this spec?"
• Users jump directly to specs without context

After (Clarity)

• Start with Foundation (3 specs)
• Check prerequisites before reading
• Find related how-to for practical usage
• Find related explanation for conceptual understanding
• Understand key concepts for each topic

Navigation Improvements

Reading progression:

Foundation
├─ Table Declaration
├─ Primary Keys
└─ Type System
    ↓
Choose based on needs:
├─ Query Algebra (if building queries)
├─ Data Operations (if working with data)
└─ Object Storage (if using large data)

Each spec now shows:

1. What to read first (prerequisites)
2. How to use it (related how-to)
3. Why it works this way (related explanation)
4. Key concepts to understand

Related

• Addresses COHESION-REVIEW.md Issue Transfer material from datajoint/datajoint-elements repository #7 (Medium Priority)
• Complements learning paths (PR Add learning paths to tutorials for better navigation #113) - specs complete the learning journey
• Works with storage decision guide (PR Add comprehensive storage codec decision guide #114) - specs provide technical details
• Part of comprehensive navigation improvement effort

[dimitri-yatsenko]

Consolidated into #119 - Documentation Cohesion Review: Comprehensive Improvements for DataJoint 2.0