add README files to improve documentation organization and structure
This commit is contained in:
@@ -0,0 +1,46 @@
|
||||
# PBS Agendas
|
||||
|
||||
This directory contains active PBS discussion agendas.
|
||||
|
||||
## Purpose
|
||||
|
||||
An agenda exists to drive a decision, not to serve as final normative text.
|
||||
|
||||
Use an agenda when:
|
||||
|
||||
- the topic is still open,
|
||||
- multiple options or tradeoffs must be evaluated,
|
||||
- the scope and non-goals need to be made explicit,
|
||||
- the order of discussion matters.
|
||||
|
||||
Remove an agenda from this directory once the topic is no longer active.
|
||||
|
||||
## Expected Format
|
||||
|
||||
An agenda should usually include:
|
||||
|
||||
1. Title
|
||||
2. Status
|
||||
3. Purpose
|
||||
4. Context
|
||||
5. Decisions to Produce
|
||||
6. Core Questions
|
||||
7. Expected Spec Material
|
||||
8. Non-Goals
|
||||
9. Inputs
|
||||
|
||||
## Writing Rules
|
||||
|
||||
- Keep the document oriented around unresolved questions.
|
||||
- Separate open questions from assumptions already fixed elsewhere.
|
||||
- Name the concrete decisions the discussion must produce.
|
||||
- Avoid drafting large blocks of final normative spec text here.
|
||||
- Prefer explicit non-goals to prevent scope drift.
|
||||
|
||||
## Exit Rule
|
||||
|
||||
An agenda should move out of the active set when:
|
||||
|
||||
- the key questions have been answered,
|
||||
- the architectural direction is clear enough to record,
|
||||
- and the topic is ready to become a decision record and then a spec update.
|
||||
Reference in New Issue
Block a user