Laurence
3fad877dee
Repo created for a reference/review of the iTelescope.net remote telescope network. This commit copies the Default Workflow in (CLAUDE.md and docs/ from the Default-Workflow repo), adds a .gitignore (secrets and scratch), and fills in state/PROJECT.md with the objective: review every telescope on the network and provide a choosing guide, using only public sources (support article and the maintained Google Sheet; the go.itelescope.net launchpad is login-only).
54 lines
2.6 KiB
Markdown
54 lines
2.6 KiB
Markdown
# Documentation policy
|
|
|
|
Two separate ideas, both about making the repo the single source of truth so that no
|
|
session ever depends on another session's chat history.
|
|
|
|
## A. State lives in committed markdown, not in the chat
|
|
|
|
Do not use chat history, context, or cache as memory. They cost tokens to carry and
|
|
vanish between sessions. Instead, everything a future session needs is written to the
|
|
`state/` directory and committed:
|
|
|
|
| File | Holds |
|
|
|------|-------|
|
|
| `PROJECT.md` | Objectives, scope, description, audience. The anchor. |
|
|
| `ARCHITECTURE.md` | How the system is built and why it is built that way. |
|
|
| `DECISIONS.md` | A dated log of decisions and their rationale. Append, never rewrite history. |
|
|
| `TODO.md` | Done / in progress / pending. The current state of play. |
|
|
| `NOTES.md` | Working notes, gotchas, environment quirks, dead ends to avoid. |
|
|
|
|
Update these as part of the work, not as an afterthought. A change to how the system
|
|
works is not finished until `ARCHITECTURE.md` or `DECISIONS.md` reflects it.
|
|
|
|
Templates for all of these are in `templates/`.
|
|
|
|
## B. Documentation is written in a separate session from the code
|
|
|
|
The user facing documentation (README, guides, API docs, changelog) is **not** written
|
|
in the same session that writes the code. This is deliberate:
|
|
|
|
- It forces the building session to leave a complete trail. If the code cannot be
|
|
documented later from git history and comments alone, the trail was not good enough.
|
|
- It keeps each session cheap and focused. A building session spends its budget
|
|
building; a documentation session spends its budget writing docs.
|
|
- It gives the docs a cold, independent reader who documents what the code actually
|
|
says, not what the author remembers intending.
|
|
|
|
### What the building session must leave behind
|
|
|
|
So the later documentation session can work with no chat history:
|
|
|
|
1. **Commit messages with full notes** - what changed, why, and any trade-offs. See
|
|
[Workflow](workflow.md).
|
|
2. **A complete PR description** - feature, tools used, what was achieved, how it works.
|
|
3. **Code comments that explain intent** - not what a line does (the code shows that)
|
|
but why it exists, what it assumes, and what would break it. Comment for a stranger
|
|
who was not in the room.
|
|
4. **Current `state/` files** - especially `ARCHITECTURE.md` and `DECISIONS.md`.
|
|
|
|
### What the documentation session does
|
|
|
|
Starts cold. Reads `git log`, the PRs, the code and its comments, and the `state/`
|
|
files. Writes the documentation from those alone. If something cannot be understood
|
|
from the repo, that is a gap to flag, not a reason to guess or to reach for lost chat
|
|
context.
|