Record decisions and designs
The Wikis app is the maintained home for engineering decision records and design documentation.
Decision records
Use a decision record to make a significant engineering choice understandable after the discussion has ended. A useful record states:
- The context
- The decision
- The alternatives considered
- The consequences
- The owner or date, when those details are confirmed
Design documentation
Use design documentation to explain the intended approach, relevant constraints, and links to confirmed architecture material. These are documentation examples, not claims about a specific Northstar system or decision.
Keep the authoritative record in Wikis
Keep the authoritative record in the Wikis app. Link to it from relevant team discussions or work items rather than maintaining competing copies in this site.
Find or maintain a record in Wikis
Search the Wikis app for the current decision or design page.
Check whether an authoritative record already exists before creating another.
Ask the record's owner to update it when the decision, design, or confirmed context changes.
Keep links to related architecture material together in the maintained wiki record.
Confirm the team's decision-record convention and wiki locations with Northstar engineering owners.
Keep records useful
Page owners should check that the record still reflects the confirmed decision or design when the work changes, a decision is superseded, or an owner identifies an error. During setup, assign a responsible role for this page and provide an approved correction route. Do not imply that a record has been reviewed until its owner confirms that review.