1.1 KiB
1.1 KiB
Guides
These guides explain the project to someone meeting it for the first time. The specification says exactly what each format is; the guides say what it is for, with examples drawn from the fixtures.
| Guide | For |
|---|---|
| Overview | What the project is, who it serves, and how its parts fit together. |
| Concepts | The ideas behind the formats, one at a time, each with a real example. |
| Walkthrough | One paper, from a flawed first reading to a corrected, reviewed and signed document. |
| Examples | Things to run: checking hashes by hand, reading a package with a few lines of Python, querying a database. |
| Rationale | Why the formats look the way they do, and the questions they leave open. |
| FAQ | Short answers to the questions people ask first. |
| Glossary | Every term, in a sentence. |
A good order for a first afternoon is the overview, then the walkthrough with the fixture open beside it, then the examples. Read the concepts when a term in the walkthrough needs more than the glossary gives.