Learn ODS: Novice to Expert

This folder is the human front door to Open Document Spec. Read it in order. Stop when the next page is more than you need.

The normative rules live in specs/. Come back to them when you need a field definition, a lint rule ID, or an implementer contract.

---

The ladder

Level	Page	You can stop here if…
0	Why ODS exists	You only wanted the idea.
1	Your first document	One trustworthy guide is enough.
2	Pick a shape	You write several kinds of docs and need the right headings.
3	Link documents	Some docs are prerequisites for others.
4	Bind files and code	The doc must point at a diagram, schema, or function.
5	Give AI a reading list	Agents should read a few files, not the whole repo.
6	Run the workspace	A team will lint, rename, and discover docs in CI.
7	Extend ODS	You need custom profiles, packs, or the engine contract.

Pocket references (any time):

• Decision cards — which profile, which key, YAML vs headings
• Common mistakes — the six errors that cause most lint failures
• FAQ — short answers to the questions the spec buries in design notes

---

How to use this track

1. Start at 00 · Why ODS exists.
2. Do the steps. Each page uses the same billing / refunds example, grown one idea at a time.
3. When a page says You can stop here, believe it. The rest is optional.
4. Jump to specs/ only for lookup, not for learning.

You are here          After you adopt
────────────          ────────────────
guides/  (learn)  →   your repo's docs/
specs/   (look up)    ods.toml + ods lint