| name | design-documents |
| description | Write a new compiler design document in docs/design-docs/. Use when the user asks to document a design, write a design doc, or record architectural decisions for the Feersum compiler. |
Writing a Design Document
Design documents live in docs/design-docs/. They are rendered by a static
site generator that sluggifies each filename: the numeric prefix and the
.md extension are stripped and the remainder becomes a folder path. For
example:
docs/design-docs/02-hygienic-macros.md → /hygienic-macros/
docs/design-docs/01-syntax-trees.md → /syntax-trees/
Steps
1. Choose a filename
Use a two-digit zero-padded numeric prefix to control ordering, followed by
lowercase hyphen-separated words that describe the topic:
docs/design-docs/03-my-new-topic.md
Do not use underscores or camelCase in filenames.
2. Write the document
A design document should contain these sections, in order:
- Title (
# heading) — matches the slug in human-readable form.
- Background / Problem — why this design is needed; what the current
state of the code is and why it is insufficient.
- Design — the proposed solution, with type signatures, data-flow
diagrams, or F# pseudocode as appropriate.
- Affected Files — a Markdown table listing files and the nature of each
change.
- Open Questions — numbered list of decisions not yet made, with a note
on the preferred direction where one exists.
Sections 4 and 5 can be omitted for short or early-stage documents, but a
Background and Design section are always expected.
Write in present tense for the current state (The binder does X) and
future/imperative for proposed changes (Change Y to Z).
3. Add a link in the README index
docs/design-docs/README.md is the index page. Add a bullet using the
sluggified folder form of the link, not the raw .md filename:
* [My New Topic](./my-new-topic/)
4. Linking between design docs
Always use the sluggified folder form when linking between documents:
<!-- Correct -->
[Syntax Trees](./syntax-trees/)
<!-- Wrong — does not work on the published site -->
[Syntax Trees](./01-syntax-trees.md)
Notes
- Documents are not guaranteed to be kept up to date after implementation.
Record significant deviations from the design in code comments rather than
retroactively editing the document.
- The README disclaimer (
The documents aren't guaranteed to be up to date, accurate, or even useful.) is intentional — leave it in place.
