Merge pull request #243 from nsidc/hazelshapiro-patch-1

Create decision records template

doc/how-to/development.md

@@ -48,7 +48,7 @@ ln -s compose.dev.yml compose.override.yml
 ### Environment variables
 
 Our development Compose file does not require any of
-[our application's environment variables](/references/envvars.md), but if you want to
+[our application's environment variables](/reference/envvars.md), but if you want to
 test with Google SSO or with a remote database, you may want to uncomment some lines in
 `compose.dev.yml`.
 
@@ -142,6 +142,6 @@ pre-commit run --all-files
 ### Third-party services
 
 See
-[our documentation on third-party services](/references/third-party-service-dependencies.md)
+[our documentation on third-party services](/reference/third-party-service-dependencies.md)
 for more, but the way they are currently set up should allow for development on
 `localhost`.

doc/reference/decision-records/000-decision-records-template.md

@@ -0,0 +1,46 @@
+---
+title: "Use a standard format for decision records"
+date: "2024-01-04"
+author: "Hazel Shapiro"
+status: "Accepted"
+---
+
+## Context
+
+In beginning this decision record, having a common format for each entry would be helpful. @hazelshapiro
+did some research and proposed Nygard's format.
+
+
+## Decision
+
+Use the template described by Michael Nygard's 2011 blog post
+[Documenting Architecture Decisions](https://www.cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
+This format includes:
+
+- Title: short noun phrases
+- Context: This section describes the forces at play. These forces are probably in tension and should be
+called out as such. The language in this section is value-neutral. It is simply describing facts.
+- Decision: This section describes our response to these forces. It is stated in full sentences, with an active voice.
+- Status: A decision may be "proposed" if the project stakeholders haven't agreed with it yet, or "accepted"
+once it is agreed. If a later ADR changes or reverses a decision, it may be marked as "deprecated" or
+"superseded" with a reference to its replacement.
+- Consequences: This section describes the resulting context, after applying the decision. All consequences
+should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and
+neutral consequences, but all of them affect the team and project in the future.
+- Consent: A non-exhaustive list of who consents to the decision.
+
+_Above is copied or summarized from the original blog post._
+
+
+## Consequences
+
+* All future decision record entries will follow the agreed-upon format.
+* Decision records will be more thorough.
+* Decision records will be more readable.
+* Decision records will take longer to author.
+
+
+## Consent
+
+* Matt Fisher
+* Hazel Shapiro

doc/reference/decision-records/001-rename-surveys.md

@@ -1,10 +1,13 @@
 ---
 title: "Rename Surveys to something else"
+author: "Hazel Shapiro"
 date: "2024-01-04"
+status: "Proposed"
 ---
 
-User feedback during testing in Oct-Dec 2023: using the word "survey" to describe how respondents input data or analysts view data was confusing.
+User feedback during testing in Oct-Dec 2023: using the word "survey" to describe how
+respondents input data or analysts view data was confusing.
 
-Possible alternatives: projects, evaluations
+Possible alternatives: "projects", "evaluations"
 
 A decision will be made by Feb 2024. This will impact the U/I as well as glossary and code.

doc/reference/decision-records/index.md

@@ -6,6 +6,8 @@ listing:
   fields:
     - "title"
     - "date"
+    - "author"
+    - "status"
   sort:
     - "date desc"
 ---