From e88c4b1ad86e786d5293c27cd18c709a399f6b75 Mon Sep 17 00:00:00 2001 From: widal001 Date: Fri, 3 May 2024 11:57:18 -0400 Subject: [PATCH] refactor: Moves grants protocol draft spec to wiki --- documentation/wiki/SUMMARY.md | 1 + .../specifications/grants-protocol.md | 135 ++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 documentation/wiki/product/deliverables/specifications/grants-protocol.md diff --git a/documentation/wiki/SUMMARY.md b/documentation/wiki/SUMMARY.md index 3851839a1..ecd9733fa 100644 --- a/documentation/wiki/SUMMARY.md +++ b/documentation/wiki/SUMMARY.md @@ -27,6 +27,7 @@ * [🏁 Open source onboarding](product/deliverables/specifications/open-source-onboarding.md) * [Co-Design Group planning](product/deliverables/specifications/co-design-group.md) * [Collaborative code challenge](product/deliverables/specifications/collaborative-code-challenge.md) + * [Grants protocol](product/deliverables/specifications/grants-protocol.md) * [Design](product/design.md) * [📖 Voice and Tone Guide](product/voice-and-tone-guide.md) diff --git a/documentation/wiki/product/deliverables/specifications/grants-protocol.md b/documentation/wiki/product/deliverables/specifications/grants-protocol.md new file mode 100644 index 000000000..a8516712d --- /dev/null +++ b/documentation/wiki/product/deliverables/specifications/grants-protocol.md @@ -0,0 +1,135 @@ +--- +description: Template page for deliverable specifications. +--- + +# Grants protocol + +## Summary details + +
FieldValue
Deliverable statusDRAFT
Link to GitHub issue[Issue number]
Key sections
+ +## Overview + +### Summary + +* **What:** Deliver the initial specification of a data protocol for financial opportunities. This will include defining the schema and fields used for opportunity listings, as well as making a plan for adding future resources that are relevant to Grants.gov. +* **Why:** Defining a shared protocol for grants data makes it easier to share information between existing systems in the grants ecosystem and helps different grant platforms align on a common standard. +* **Who** + * Internal development team + * Grants ecosystem partners (e.g. USDR, OpenGrants.io, etc.) + +### Business value + +#### Problem + +\[2-3 sentences describing the problem that this deliverable attempts to solve] + +#### Value + +\[2-3 sentences describing the value that this deliverable provides by addressing the problem] + +#### Goals + +* \[Business goal 1] +* \[Business goal 2] + +#### Non-goals + +* \[Description of something that is explicitly not a goal of this deliverable] +* \[Description of something that is explicitly not a goal of this deliverable] + +#### Assumptions and dependencies + +* \[Description of assumption that informs or impacts the rest of this deliverable] + +### User stories + +* As a **\[type of user 1]**, I want to: + * \[perform action 1], so that \[goal or motivation for action] + * \[perform action 2], so that \[goal or motivation for action] +* As a **\[type of user 2]**, I want to: + * \[perform action 1], so that \[goal or motivation for action] + * \[perform action 2], so that \[goal or motivation for action] + +## Definition of done + +Following sections describe the conditions that must be met to consider this deliverable "done". + +#### **Must have** + +*User experience:* +- [ ] The protocol has a name that is approved by Emily Ianacone in her role as UX lead for Grants.gov. +- [ ] Documentation is published that explains the protocol in an intuitive, accessible manner. +- [ ] **Translation:** There are clear plans for putting tools and processes in place that translate the protocol's meaning and documentation into multiple languages. For instance, this could include building a data dictionary that defines the `fields` and `types` in multiple languages. + +- *Financial opportunities specification:* + - [ ] A complete draft specification is available that can be used to represent opportunity listings from Grants.gov, to be returned over the new Simpler Grants.gov APIs. +- *Generic specification:* + - [ ] **Required fields:** One or more minimum necessary fields for any financial opportunity are included in the spec as required fields. An example field is the due date of applications for the financial opportunity. + - [ ] **Optional fields:** One or more fields that are either necessary for Grants.gov specifically, or are often used for financial opportunities in general but are not required, are implemented. These will be fields that have well-designed implementations that any implementer of the protocol can optionally implement (by choosing them from a catalog of schemas). An example field is the federal opportunity number. + - [ ] **Types:** For all these fields, well-designed field types exist and are joined one-to-many on these fields. (This means that every `type` can be used by one or more `field`s.) For instance, there could be a type for DateTime, a type for Geospatial, etc. Types can also include other types: such as an object with `type:Application` might include a field that has a `type:Timestamp`. Every `field` that is implemented has one and only one `type`. + - [ ] **Extensions:** There exists an easy method for any implementer of the protocol to extend the protocol to custom fields and types. These custom fields and types are not necessarily reflected in the shared protocol specification, and can be implemented "locally." Custom extensions are easy to share and reuse with other projects. + - [ ] **Proposals:** There are clear plans for putting processes and tools in place so that anyone can propose that their "local" extensions should become optional or required parts of the common spec. + - [ ] **Decisionmaking:** There are clear plans for putting processes and tools in place that support community decisionmaking to accept or reject proposals for modifications to the spec. +- *Schema validation:* + - [ ] A schema validator is built that verifies whether a given implementation of the protocol (or perhaps, an individual response object provided to or from an API) is a valid implementation of the shared protocol. + - [ ] The schema validator is setup to run automatically on Grants.gov APIs. + - [ ] Nice-to-have: the schema validator is provided through a package manager (such as `pip` for Python packages or `npmjs.com` for Javascript). +- *Integration:* + - [ ] A decision has been made on where the code for the protocol will live -- either as part of `simpler-grants-gov` repo or a new open source repo -- and the code is hosted there publicly. + - [ ] Code is deployed to `main` & PROD + - [ ] Services are live in PROD (may be behind feature flag) + - [ ] Metrics are published in PROD. + - [ ] Translations are live in PROD (if necessary) + +#### **Nice to have** + +* [ ] \[Must-have condition 1] +* [ ] \[Must-have condition 2] + +#### Not in scope + +* \[Description of item that is explicitly out of scope] + +## Measurement + +### Proposed metrics + +* \[Metric 1] +* \[Metric 2] + +### Location for publishing metrics + +\[Description of where/how metrics will be shared with the public] + +## Open questions + +
+ +[Open question 1] + + + +
+ +
+ +[Open question 2] + + + +
+ +## Logs + +### Change log + +Major updates to the content of this page will be added here. + +
DateUpdateNotes
+ +### Implementation log + +Use this section to indicate when acceptance criteria in the "Definition of done" section have been completed, and provide notes on steps taken to satisfy this criteria when appropriate. + +
DateCriteria completedNotes