Skip to content

Good — then we’ll lock the reference template properly and make it hard to misuse.

Below is the final, authoritative reference_page_template.md for DAQS. This is the version I’d actually enforce in reviews.

You can copy this as-is.

Reference Page Template (DAQS)

Use this template for all pages under reference/. If a page needs explanation, motivation, or step-by-step flow, it does not belong here.

# <Concept name>

<One concise sentence describing what this concept is.  
No motivation. No context. No examples yet.>

---

## Definition

<A precise, unambiguous definition.  
This section answers: “What is this, exactly?”>

---

## Purpose (system-level)

<Explain what role this concept plays in DAQS.  
This is not “why the user should care”, but how the system uses it.>

---

## Structure

<Describe the structural shape of this concept.  
Use code blocks or tables where applicable.>

Example:

```json
{
  "field": "value"
}

Fields / Properties

Name Type Required Description
field string Yes What this field represents

Rules:

  • Be explicit
  • No vague descriptions
  • “Required” means required, not “usually present”

Behaviour

Focus on deterministic behaviour and side effects.>

Examples:

  • how data is interpreted
  • how missing values are handled
  • how this affects validation results

Constraints

These are rules that cannot be violated.>

  • Constraint 1
  • Constraint 2

Error conditions

Notes

---

## Non-negotiable rules for reference pages

### ❌ What reference pages must NOT contain
- step-by-step instructions
- learning flow
- “first do this, then that”
- motivational language
- beginner explanations

If you feel the urge to explain *how to use* something → stop.  
That content belongs in `learning_path/`.

---

### ✅ What reference pages MUST do
- be scannable
- be precise
- be complete
- answer a question in under 30 seconds

If a page cannot be skimmed, it’s not a reference page.

---

## Quick self-check (use this before committing)

A reference page is correct if you can answer **yes** to all of these:

- Can I read only the headings and still understand the concept?
- Is every statement factual and verifiable?
- Could this page be used without reading any other page?
- Is there exactly one `#` heading?

If not, fix it before adding content.

---

## Status

This template is **authoritative** for DAQS reference documentation.

Deviations should be rare and intentional.

---