Notation & Cross-References
Everything you need to know to read and navigate this handbook effectively.
Page components
Each article uses consistent visual components to convey information:
Hero
A large, visually prominent introduction at the top of most pages. It sets context and signals the article's main topic.
Figure
Diagrams, screenshots, and illustrations throughout the text. Figures are captioned and help explain concepts visually. Most are Mermaid diagrams (flowcharts, sequence diagrams, state machines).
Callout boxes
Short highlighted sections for emphasis:
- ℹ️ Info: Additional context or a tip to deepen understanding
- ✅ Success / Pro: Recommended approach or best practice
- ⚠️ Warning: Common pitfall or important caution
- ❌ Danger: Avoid this; high-risk pattern
- 💡 Takeaway: Key insight to remember
Tabs
Code examples in multiple languages (Python, Go, Node.js) or to compare approaches. Click to switch between options.
Showcase
Side-by-side comparison boxes to contrast two approaches (good vs. risky, or framework A vs. framework B).
Vs
A two-column comparison of contrasting concepts (e.g., REST vs. GraphQL, monolith vs. microservices).
Checklist
Interactive checkboxes for validation lists, readiness checks, or task guides.
ProsCons
Organized comparison of advantages and disadvantages for decision-making.
Metadata & tags
Every article includes:
| Field | Meaning |
|---|---|
| sidebar_position | Order in the section (lower = earlier in nav) |
| difficulty | intro, intermediate, or advanced |
| estimatedTime | Reading time in minutes |
| docType | guide (procedural), concept (explanation), reference (lookup), or architecture (deep-dive) |
| keywords | Search terms for discoverability |
| tags | Category labels (e.g., "resilience", "performance") |
| lastReviewed | When the article was last fact-checked |
Difficulty levels
Each article is tagged with a difficulty. This tells you what prior knowledge is expected:
| Level | When to read | Prerequisites |
|---|---|---|
| intro | First time on a topic | Prerequisites page covers it |
| intermediate | After reading intro-level sections in the area | Prior "intro" articles from the same section |
| advanced | Deep dive with nuance | Prior "intro" and "intermediate" articles; comfort with trade-offs |
Start at intro for unfamiliar topics. Progress only when concepts feel solid.
Document types
Each article is marked with a docType:
| Type | Purpose | How to use |
|---|---|---|
| guide | Step-by-step or sequential explanation | Read top-to-bottom for learning |
| concept | Explanation of a core idea or pattern | Read to understand; reference as needed |
| reference | Lookup information, quick answers | Skim for your specific question |
| architecture | Deep-dive design patterns or systems | Read carefully; great for team discussion |
Diagrams & Mermaid
Most diagrams in this handbook are Mermaid (text-based, version-controlled). You'll see:
- Flowcharts (TB / LR): Show process flow or decision logic
- Sequence diagrams: Illustrate interactions over time (client-server, distributed calls)
- State machines: Model state transitions and triggers
- Class diagrams: Show relationships between concepts
- Gitgraph: Illustrate branching patterns in deployment or version control
All Mermaid diagrams are readable even if rendering fails; the text explains them.
Code examples
Code samples appear in a few styles:
Pseudocode
Language-agnostic high-level code illustrating concepts, not production code. Looks like:
if request.timeout < system.elapsed:
throw TimeoutError
Multi-language tabs
Practical examples in Python, Go, or Node.js. Click tabs to switch. These show real patterns you can adapt.
YAML / Configuration
Infrastructure, deployment, or configuration examples (e.g., Kubernetes manifests, CI/CD pipeline configs).
Cross-reference conventions
Internal links
Links to other handbook sections use shorthand:
[Foundational Concepts](/docs/foundational-concepts)→ Link to another section- Relative links like
../testing-strategyrefer to sibling sections
External links
Links to external resources end with ↗️ and open in a new tab:
[The Twelve-Factor App ↗️](https://12factor.net/)
Section index cards
Many sections end with a visual index of sub-topics. Click any to jump to that article.
Reading strategies
Linear reader? Start at Learning Order, pick your tier, and move sequentially.
Jump around? Use Cross-References to find related articles. The table shows common "if you're reading X, also see Y" connections.
Team learner? Read an article, then discuss the trade-offs with your team. Share sections using the browser's "Copy Link" feature.
Reference seeker? Bookmark sections you return to often. Use browser search (Ctrl+F / Cmd+F) to find concepts within articles.
Notation summary
| Element | Meaning |
|---|---|
| 📝 | Example or illustration |
| ↗️ | External link (new tab) |
| bold | Key term or important phrase |
code | Technical term, variable, or command |
> quote | Emphasized or quoted insight |
| ❌ ✅ | Anti-pattern vs. best practice |
| Tier 1, Tier 2, etc. | Learning progression level |
Takeaway
This handbook is designed to be scannable, searchable, and referenceable. Use the components, metadata, and cross-references to navigate in whatever way suits your learning style. If something is unclear, check Cross-References to see related articles that might provide context.
Now that you know how to read this handbook, head to Learning Order or Audience & Scope to find your starting point.