Add learning paths to tutorials for better navigation

[dimitri-yatsenko]

Summary

Adds clear skill-based learning paths to the tutorials index, addressing navigation confusion identified in the cohesion review.

Problem

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

• User journey unclear: tutorials → how-to → reference progression not explicit
• No recommended reading order by skill level
• Examples don't clearly indicate progression level
• Users asking "which tutorial should I do next?" or "am I ready for advanced topics?"

Solution

New "Learning Paths" section with 4 clear skill-based progressions:

🌱 New to DataJoint (Beginner)

• Goal: Understand core concepts and build first pipeline
• Path: 5 basics tutorials + 1 example (~3 hours total)
• Time estimates: 30-45 min per tutorial
• Next step: Read Relational Workflow Model

🚀 Building Production Pipelines (Intermediate)

• Goal: Create automated, scalable workflows
• Prerequisites: Complete basics or equivalent
• Path: Computation → Object Storage → Distributed → Practice examples
• Next steps: 3 specific how-to guides (run computations, distributed, errors)

🧪 Domain-Specific Applications

• Goal: Build scientific pipelines for your field
• Prerequisites: Basics + computation model
• Neuroscience: 3 domain tutorials (calcium imaging, ephys, brain atlas)
• General: 2 pattern examples (reservations, many-to-many)
• Next step: Explore DataJoint Elements

🔧 Extending DataJoint (Advanced)

• Goal: Customize for specialized needs
• Prerequisites: Proficient with basics and production
• Path: Custom codecs → JSON → SQL comparison
• Next steps: Codec API spec, codec development guide

Design Decisions

Emoji indicators:

• 🌱 Beginner (approachable)
• 🚀 Production (action/scale)
• 🧪 Domain/Science (research)
• 🔧 Advanced/Customization (technical depth)

Structure per path:

1. Clear goal statement (what you'll achieve)
2. Prerequisites (if not beginner)
3. Numbered tutorial sequence
4. Time estimates (for beginners only - helps planning)
5. "Next:" links to follow-up resources

Placement:

• After Quick Start (shows DataJoint works)
• Before detailed tutorial sections (provides roadmap before browsing)

User Impact

Before (Confusion)

• "I finished the first tutorial, what next?"
• "Am I ready for distributed computing?"
• "Which tutorials apply to neuroscience?"
• Users browse all tutorials without clear progression

After (Clarity)

• Choose path based on explicit goal
• Know prerequisites before starting
• Understand time commitment (beginners)
• Clear next steps after completing path
• Navigate directly to relevant domain tutorials

Visual Structure

Tutorials/
├── Quick Start (shows it works)
├── Learning Paths ← NEW (navigation guide)
│   ├── 🌱 New to DataJoint
│   ├── 🚀 Building Production Pipelines
│   ├── 🧪 Domain-Specific Applications
│   └── 🔧 Extending DataJoint
├── Basics (detailed reference)
├── Examples (detailed reference)
├── Domain Tutorials (detailed reference)
└── Advanced Topics (detailed reference)

Cross-References

Each path links to:

• Tutorials (numbered sequence)
• Explanation docs (conceptual understanding)
• How-to guides (practical tasks)
• Reference specs (technical details)
• External resources (Elements)

Related

• Addresses COHESION-REVIEW.md Issue Update github repo references after name change #5 (Medium Priority)
• Complements installation clarity (PR Clarify DataJoint 2.0 pre-release status in installation guide #111) - users know where to start after install
• Works with secrets guide (PR Add comprehensive secrets and credentials management guide #112) - users configure then learn
• Part of overall navigation improvement effort

[dimitri-yatsenko]

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