18 lines
1.1 KiB
Markdown
18 lines
1.1 KiB
Markdown
# Guides
|
|
|
|
These guides explain the project to someone meeting it for the first time.
|
|
The [specification](../spec/README.md) says exactly what each format is; the guides say what it is for, with examples drawn from the fixtures.
|
|
|
|
| Guide | For |
|
|
| --- | --- |
|
|
| [Overview](overview.md) | What the project is, who it serves, and how its parts fit together. |
|
|
| [Concepts](concepts.md) | The ideas behind the formats, one at a time, each with a real example. |
|
|
| [Walkthrough](walkthrough.md) | One paper, from a flawed first reading to a corrected, reviewed and signed document. |
|
|
| [Examples](examples.md) | Things to run: checking hashes by hand, reading a package with a few lines of Python, querying a database. |
|
|
| [Rationale](rationale.md) | Why the formats look the way they do, and the questions they leave open. |
|
|
| [FAQ](faq.md) | Short answers to the questions people ask first. |
|
|
| [Glossary](glossary.md) | 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.
|