Skip to content

Perfect. This completes the foundation. Below are two canonical, copy-paste templates that enforce the style guide you just locked in.

I’ll keep this strict and mechanical on purpose.

You can store these as:

docs/reference/templates/
├── learning_page_template.md
└── reference_page_template.md

Learning Page Template

Use this template for all pages under learning_path/.

# <Page title>

<Short definition of the concept in 2–3 sentences.  
State clearly what this page explains.>

---

## Why this matters

<Explain why this concept exists from a DAQS system perspective.  
Focus on consequences, not usage instructions.>

---

## Minimal working example

<Introduce the smallest possible example that demonstrates the concept.>

```<language>
<minimal valid example>

Rules and constraints

  • Rule 1
  • Rule 2
  • Rule 3

Common mistakes

Show the incorrect example first.>

``` 

<Explain why this is incorrect and what breaks as a result.>

---

## Mental model

<Provide one strong analogy or conceptual framing that helps readers remember this concept.  
Avoid metaphors that introduce ambiguity.>

---

## Rule of thumb

> <One concise sentence the reader can remember and apply.>

---

## What this page does not cover

<Explicitly list topics intentionally excluded from this page.  
Point to other sections if relevant.>

Notes

  • Do not remove sections unless they are genuinely irrelevant.
  • Keep examples minimal.
  • One concept per page.

Reference Page Template

Use this template for all pages under reference/.

# <Concept or item name>

<One-sentence factual description of what this is.  
No narrative. No motivation.>

---

## Definition

<Formal definition of the concept.  
Be precise and unambiguous.>

---

## Structure

<Describe the structure, fields, or shape.  
Use tables or bullet lists where helpful.>

Example:

```json
{
  "field": "description"
}

Fields / Properties

Name Type Required Description
field string Yes Explanation

Behaviour

State invariants and side effects.>

Constraints

  • Constraint 1
  • Constraint 2

Notes

### Notes
- No storytelling.
- No step-by-step instructions.
- No “why should I care” sections.

---

## Enforcement rule (important)
If a page:
- follows the **learning template** → it belongs in `learning_path/`
- follows the **reference template** → it belongs in `reference/`

If it fits neither cleanly → split the content.

---

## Optional next step (recommended)
To make this stick long-term, we can:

1. Add a **pre-commit check** for:
   - multiple `#` headings
   - missing sections
2. Add a **template generator script**
3. Audit 3–5 existing pages and refactor them once