From 8f8d3e2317b856dd26620b2f911c642a3b39c046 Mon Sep 17 00:00:00 2001 From: widal001 Date: Tue, 10 Oct 2023 13:05:32 -0400 Subject: [PATCH 01/19] feat: Creates the Search UI deliverable spec Copies the deliverable spec template and populates the short description and business description section --- .../individual_milestones/search_ui.md | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 documentation/milestones/individual_milestones/search_ui.md diff --git a/documentation/milestones/individual_milestones/search_ui.md b/documentation/milestones/individual_milestones/search_ui.md new file mode 100644 index 000000000..75b58da32 --- /dev/null +++ b/documentation/milestones/individual_milestones/search_ui.md @@ -0,0 +1,138 @@ +# Search UI Launch + +| Field | Value | +| --------------- | ---------------------------------------------------------- | +| Document Status | Completed | +| Epic Link | [Issue 89](https://github.com/HHS/grants-equity/issues/89) | +| Epic Dashboard | [Product Roadmap](https://github.com/orgs/HHS/projects/12) | +| Product Owner | Lucas Brown | +| Document Owner | Billy Daly | +| Lead Developer | Aaron Couch | +| Lead Designer | Andy Cochran | + + +## Short description + + +Launch a minimum viable search feature for Simpler Grants.gov that allows non-technical users to filter funding opportunities by *at least* one field and/or by keywords. + +## Goals + +### Business description & value + + +The launch of a basic search feature primarily proves our ability to integrate front-end and backend systems in a production environment, while also providing a minimum viable product (MVP) that we can leverage for targeted user testing. + +As a result, this deliverable aims to: + +- Successfully integrate the front-end with the API for the first time in production +- Create the internal infrastructure needed to support future search functionality +- Establish simpler.grants.gov as the location where that functionality will be released +- Deliver a minimum viable product (MVP) that we can use to collect user feedback from a targeted set of stakeholders + +By contrast, this MVP version of search ***does not*** attempt to: + +- Replicate *all* of the search functionality currently supported by grants.gov +- Dramatically improve the accuracy of search results relative to those returned by grants.gov +- Replace grants.gov as the primary platform applicants use to find funding opportunities + +### 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} + +## Technical description + +### {Optional Sub-deliverable} + + +{List reqiurements specific to this sub-deliverable, options to consider, etc.} + +### Definition of done + + +- [ ] [to be added] +- [ ] 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) + +### Proposed metrics for measuring goals/value/definition of done + + +1. {Metric 1} + +### Destination for live updating metrics + + +## Planning + +### Assumptions & dependencies + + +What capabilities / milestones do we expect to be in place at the beginning of work +on this milestone? + +- [ ] [to be added] + +Are there any notable capabilities / milestones do NOT we expect to be in place at the +beginning of work on this milestone? + +- [ ] [to be added] + +### Open questions + + +- [ ] [to be added] + +### Not doing + + +The following work will *not* be completed as part of this milestone: + +1. [to be added] + +## Integrations + +### Translations + + +Does this milestone involve delivering any content that needs translation? + +If so, when will English-language content be locked? Then when will translation be +started and completed? + +### Services going into PROD for the first time + + +This can include services going into PROD behind a feature flag that is not turned on. + +1. [to be added] + +### Services being integrated in PROD for the first time + + +Are there multiple services that are being connected for the first time in PROD? + +1. [to be added] + +### Data being shared publicly for the first time + + +Are there any fields being shared publicly that have never been shared in PROD before? + +1. [to be added] + +### Security considerations + + +Does this milestone expose any new attack vectors or expand the attack surface of the product? + +If so, how are we addressing these risks? + +1. [to be added] From 900981957da6710c267c5e83f89ca4708b287ac1 Mon Sep 17 00:00:00 2001 From: widal001 Date: Tue, 10 Oct 2023 15:30:48 -0400 Subject: [PATCH 02/19] feat: Adds assumptions & dependencies to search UI --- .../individual_milestones/search_ui.md | 59 +++++++++++++------ 1 file changed, 41 insertions(+), 18 deletions(-) diff --git a/documentation/milestones/individual_milestones/search_ui.md b/documentation/milestones/individual_milestones/search_ui.md index 75b58da32..d6548438a 100644 --- a/documentation/milestones/individual_milestones/search_ui.md +++ b/documentation/milestones/individual_milestones/search_ui.md @@ -1,4 +1,4 @@ -# Search UI Launch +# Search MVP | Field | Value | | --------------- | ---------------------------------------------------------- | @@ -14,7 +14,7 @@ ## Short description -Launch a minimum viable search feature for Simpler Grants.gov that allows non-technical users to filter funding opportunities by *at least* one field and/or by keywords. +Launch a minimum viable search feature for Simpler Grants.gov that allows non-technical users to filter funding opportunities by *at least* one field and by keywords. ## Goals @@ -75,64 +75,87 @@ By contrast, this MVP version of search ***does not*** attempt to: ### Assumptions & dependencies -What capabilities / milestones do we expect to be in place at the beginning of work -on this milestone? +What functionality do we expect to be in place ***before*** work starts on this deliverable? -- [ ] [to be added] +- **Front-end:** The Search UI will build on the front-end work completed in both the initial static site launch and the subsequent improvements that created the following functionality: + - **Front-end CI/CD:** Automatically tests and deploys front-end code + - **Foundational UI:** Enforces a consistent user interface and web design system across the frontend + - **Translation Process:** Facilitates and publishes translations of front-end content in multiple languages +- **API:** The Search API will build on the existing backend work completed to launch the GET Opportunities endpoint which delivered the following functionality: + - **Backend CI/CD:** Automatically tests and deploys backend code + - **Database Replica:** Maintains eventual consistency (with low latency) between the data in grants.gov and simpler.grants.gov and ensures that simpler.grants.gov services remain available when grants.gov services experience downtime + - **Data Architecture:** Enables simpler.grants.gov to read data from an updated (and simplified) data model -Are there any notable capabilities / milestones do NOT we expect to be in place at the -beginning of work on this milestone? +What functionality do we expect to be in place by ***the end*** of work on this deliverable? -- [ ] [to be added] +- **[Incident Response](https://github.com/HHS/grants-equity/issues/373):** Ensures that we have a robust incident response plan in place when simpler.grants.gov services are interrupted +- **[Search API](https://github.com/HHS/grants-equity/issues/90):** Enables system-to-system users to access the search features through the API +- **Search Page:** Enables all other users to access the search features through the user interface +- **[Opportunity Listing Page](https://github.com/HHS/grants-equity/issues/277):** Displays basic information about a given funding opportunity accessed from the search page +- **User Research Incentives:** Enables us to engage stakeholders for user testing of the new search functionality + +Is there any notable functionality we do ***not*** expect to be in place before works starts on this deliverable? + +- **AuthN/AuthZ:** Authentication (AuthN) and Authorization (AuthZ) will be the focus of a subsequent deliverable, so the MVP is not expected to support any features that require users to be logged in. ### Open questions -- [ ] [to be added] +#### Does the metadata and the text of the opportunity need to be translated? + +TODO + +#### What metadata is currently available about each opportunity? + +TODO ### Not doing -The following work will *not* be completed as part of this milestone: +The following work will *not* be completed as part of this deliverable: -1. [to be added] +- **Personalization:** Because the MVP will not support a login experience, any personalized features that require authentication (e.g. saving searches) are explicitly descoped from this deliverable. +- **Full Text Search:** The MVP is only expected to include (a subset of) filtering based on opportunity metadata that is already available in the existing grants.gov database, so searching the full text of the opportunity is explicitly descoped from this deliverable. +- **Full Text Listing:** Similarly, the first iteration of the opportunity listing page delivered is only expected to include opportunity fields that are already available in the existing grants.gov database. As a result, displaying the full text of the opportunity within the listing page is explicitly descoped from this deliverable. ## Integrations ### Translations -Does this milestone involve delivering any content that needs translation? +*Does this milestone involve delivering any content that needs translation?* -If so, when will English-language content be locked? Then when will translation be -started and completed? +*If so, when will English-language content be locked? Then when will translation be started and completed?* ### Services going into PROD for the first time This can include services going into PROD behind a feature flag that is not turned on. -1. [to be added] +1. **Search API:** Search functionality will be exposed via the API for the first time in this deliverable +2. **Search UI:** Search functionality will be exposed via the user interface for the first time in this deliverable ### Services being integrated in PROD for the first time Are there multiple services that are being connected for the first time in PROD? -1. [to be added] +1. **API + Front-end:** This deliverable represents the first time the simpler.grants.gov front-end and API will be integrated in production ### Data being shared publicly for the first time Are there any fields being shared publicly that have never been shared in PROD before? -1. [to be added] +1. TODO ### Security considerations Does this milestone expose any new attack vectors or expand the attack surface of the product? +1. TODO + If so, how are we addressing these risks? -1. [to be added] +1. TODO From 3704e4d63c947e8f0c7b1323e7048887e3f2a2d6 Mon Sep 17 00:00:00 2001 From: widal001 Date: Tue, 10 Oct 2023 17:44:19 -0400 Subject: [PATCH 03/19] feat: Adds user stories to search MVP spec --- .../individual_milestones/search_ui.md | 49 +++++++++++-------- 1 file changed, 29 insertions(+), 20 deletions(-) diff --git a/documentation/milestones/individual_milestones/search_ui.md b/documentation/milestones/individual_milestones/search_ui.md index d6548438a..1687894c2 100644 --- a/documentation/milestones/individual_milestones/search_ui.md +++ b/documentation/milestones/individual_milestones/search_ui.md @@ -14,7 +14,7 @@ ## Short description -Launch a minimum viable search feature for Simpler Grants.gov that allows non-technical users to filter funding opportunities by *at least* one field and by keywords. +Launch a minimum viable search feature for Simpler Grants.gov that allows users to filter funding opportunities by *at least* one field and by keywords. ## Goals @@ -39,19 +39,27 @@ By contrast, this MVP version of search ***does not*** attempt to: ### 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} +- As a **system-to-system user**, I want: + - To be able to access all of the search features via the API, so that search results are the same whether I'm using the API or the UI. + - The search functionality to be outlined in the API docs, so that I don't have to rely on experimentation to learn how to search for opportunities. +- As a **prospective applicant**, I want: + - To be able to be able to search with filters applied, so that the only search results returned are ones that match both the keyword and field-based criteria I specified + - The opportunity listing page to have a link to apply on grants.gov, so that I don't have to repeat my search on grants.gov after finding an opportunity I want to apply for on simpler.grants.gov + - To receive an incentive if I participate in user research for simpler.grants.gov, so that I am fairly compensated for the time that I invest in testing out new features and answering questions +- As a **project maintainer**, I want: + - To be notified when simpler.grants.gov experiences downtime, so that I can quickly troubleshoot the issue with minimal impact on end users + - The system architecture we create for this deliverable to support future search features as well, so that we don't need to discard and re-build critical infrastructure ## Technical description -### {Optional Sub-deliverable} +### Search API -{List reqiurements specific to this sub-deliverable, options to consider, etc.} +TODO + +### Search UI + +TODO ### Definition of done @@ -65,7 +73,7 @@ By contrast, this MVP version of search ***does not*** attempt to: ### Proposed metrics for measuring goals/value/definition of done -1. {Metric 1} +1. TODO ### Destination for live updating metrics @@ -77,22 +85,23 @@ By contrast, this MVP version of search ***does not*** attempt to: What functionality do we expect to be in place ***before*** work starts on this deliverable? -- **Front-end:** The Search UI will build on the front-end work completed in both the initial static site launch and the subsequent improvements that created the following functionality: - - **Front-end CI/CD:** Automatically tests and deploys front-end code - - **Foundational UI:** Enforces a consistent user interface and web design system across the frontend - - **Translation Process:** Facilitates and publishes translations of front-end content in multiple languages -- **API:** The Search API will build on the existing backend work completed to launch the GET Opportunities endpoint which delivered the following functionality: - - **Backend CI/CD:** Automatically tests and deploys backend code - - **Database Replica:** Maintains eventual consistency (with low latency) between the data in grants.gov and simpler.grants.gov and ensures that simpler.grants.gov services remain available when grants.gov services experience downtime - - **Data Architecture:** Enables simpler.grants.gov to read data from an updated (and simplified) data model +- **Front-end:** The search UI will build on the front-end work completed in both the [initial static site launch](https://github.com/HHS/grants-equity/issues/62) and the [subsequent improvements](https://github.com/HHS/grants-equity/issues/568) that created the following functionality: + - **[Front-end CI/CD](https://github.com/HHS/grants-equity/issues/58):** Automatically tests and deploys front-end code + - **[Foundational UI](https://github.com/HHS/grants-equity/issues/60):** Enforces a consistent user interface and web design system across the frontend + - **[Translation Process](https://github.com/HHS/grants-equity/issues/81):** Facilitates and publishes translations of front-end content in multiple languages +- **API:** The search API will build on the existing backend work completed to launch the [GET Opportunities endpoint](https://github.com/HHS/grants-equity/issues/70) which delivered the following functionality: + - **[Backend CI/CD](https://github.com/HHS/grants-equity/issues/57):** Automatically tests and deploys backend code + - **[Database Replica](https://github.com/HHS/grants-equity/issues/54):** Maintains eventual consistency (with low latency) between the data in grants.gov and simpler.grants.gov and ensures that simpler.grants.gov services remain available when grants.gov services experience downtime + - **[Data Architecture](https://github.com/HHS/grants-equity/issues/125):** Enables simpler.grants.gov to read data from an updated (and simplified) data model + - **[API Docs](https://github.com/HHS/grants-equity/issues/71):** Documents the API endpoints released with each deliverable What functionality do we expect to be in place by ***the end*** of work on this deliverable? - **[Incident Response](https://github.com/HHS/grants-equity/issues/373):** Ensures that we have a robust incident response plan in place when simpler.grants.gov services are interrupted - **[Search API](https://github.com/HHS/grants-equity/issues/90):** Enables system-to-system users to access the search features through the API -- **Search Page:** Enables all other users to access the search features through the user interface +- **[Search Page](https://github.com/HHS/grants-equity/issues/576):** Enables all other users to access the search features through the user interface - **[Opportunity Listing Page](https://github.com/HHS/grants-equity/issues/277):** Displays basic information about a given funding opportunity accessed from the search page -- **User Research Incentives:** Enables us to engage stakeholders for user testing of the new search functionality +- **[User Research Incentives](https://github.com/HHS/grants-equity/issues/84):** Enables us to engage stakeholders for user testing of the new search functionality Is there any notable functionality we do ***not*** expect to be in place before works starts on this deliverable? From 826f4d2ee53dd33df14e52b5ec2b3c28ecbfb10a Mon Sep 17 00:00:00 2001 From: widal001 Date: Tue, 10 Oct 2023 17:51:19 -0400 Subject: [PATCH 04/19] refactor: Renames search_ui.md to search_mvp.md --- .../individual_milestones/{search_ui.md => search_mvp.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename documentation/milestones/individual_milestones/{search_ui.md => search_mvp.md} (100%) diff --git a/documentation/milestones/individual_milestones/search_ui.md b/documentation/milestones/individual_milestones/search_mvp.md similarity index 100% rename from documentation/milestones/individual_milestones/search_ui.md rename to documentation/milestones/individual_milestones/search_mvp.md From 11679b1f38dcbd59fa7019b606e9644e4dd3d303 Mon Sep 17 00:00:00 2001 From: widal001 Date: Mon, 16 Oct 2023 09:25:54 -0400 Subject: [PATCH 05/19] feat: Add DoD, metrics, and tech description to Search MVP --- .../individual_milestones/search_mvp.md | 69 ++++++++++++++++--- 1 file changed, 58 insertions(+), 11 deletions(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index 1687894c2..1bcc81987 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -14,7 +14,9 @@ ## Short description -Launch a minimum viable search feature for Simpler Grants.gov that allows users to filter funding opportunities by *at least* one field and by keywords. +- **What:** Launch a minimum viable search feature for Simpler Grants.gov that allows users to filter and sort funding opportunities by *at least* one field and by keywords. +- **Why:** Proves the successful integration of front-end and backend systems in production and delivers basic search functionality that we can begin to leverage for user testing +- **Who:** Targeted group of external stakeholders with whom we'd like to conduct user research and testing ## Goals @@ -46,6 +48,7 @@ By contrast, this MVP version of search ***does not*** attempt to: - To be able to be able to search with filters applied, so that the only search results returned are ones that match both the keyword and field-based criteria I specified - The opportunity listing page to have a link to apply on grants.gov, so that I don't have to repeat my search on grants.gov after finding an opportunity I want to apply for on simpler.grants.gov - To receive an incentive if I participate in user research for simpler.grants.gov, so that I am fairly compensated for the time that I invest in testing out new features and answering questions + - Filters and search terms to be added to the url, so that I can save or share the link to a particular set of search results - As a **project maintainer**, I want: - To be notified when simpler.grants.gov experiences downtime, so that I can quickly troubleshoot the issue with minimal impact on end users - The system architecture we create for this deliverable to support future search features as well, so that we don't need to discard and re-build critical infrastructure @@ -55,25 +58,65 @@ By contrast, this MVP version of search ***does not*** attempt to: ### Search API -TODO +The ability to search and filter opportunities should be provided through an API endpoint, which allows the user to: -### Search UI +- Search the list of opportunities with open ended key words +- Filter the search results by *at least* one structured field (e.g. award date, opportunity type, etc.) +- Sort the search results based on the value of *at least* -TODO +Through the design and development of this API endpoint, the team should answer the following questions and record the decisions in one or more ADRs: + +- How should search and filter criteria be passed to the API endpoint used for search? +- How should we support basic logic such as greater than, less than, as well as and/or/not conditions? +- Which fields should support filtering and sorting? +- Do we use an existing search service (e.g. Elasticsearch) or build our own? + +### Search Page + +The primary page we'll need to deliver for the user interface (UI) is a search page, which should allow users to: + +- Enter key words to search the list of funding opportunities +- Filter search results by *at least* one structured field (e.g. award date, opportunity type, etc.) +- View a common set of fields for each opportunity returned by the search (e.g. title, award date, summary, etc.) +- Sort the set of results returned by *at least* one structured field (e.g. award date, title, etc.) + +### Opportunity Listing Page + +The secondary page we want to deliver within the user interface (UI) is an opportunity listing page, which should: + +- Display a consistent list of metadata about each opportunity +- Use only fields that are available in the existing grants.gov cloud database +- Link to the corresponding opportunity in the existing grant.gov interface + +**Note:** This is a stretch goal for this deliverable and may be substituted with a direct link to the grants.gov page for a given opportunity from the search results. ### Definition of done -- [ ] [to be added] -- [ ] 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) +- [ ] Basic requirements: + - [ ] Code is deployed to `main` & PROD through our CI/CD pipeline + - [ ] Services are live in PROD (may be behind feature flag) + - [ ] Translations are live in PROD (if necessary) + - [ ] All new services have passed a security review (if necessary) + - [ ] Data needed for metrics is actively being captured in PROD + - [ ] Key architectural decisions made about this deliverable are documented publicly +- [ ] Functional requirements: + - [ ] Users can search for opportunities by key word + - [ ] Users can filter search results by *at least one* structured field (e.g. award date, opportunity type, etc.) + - [ ] Users can sort search results by *at least* one structured field (e.g. award date, title, etc.) + - [ ] All of the search features available in the UI are also available via the API, and vice versa + - [ ] Search criteria are reflected in the URL so that users can bookmark or share the link to a given set of search results + - [ ] Users can access the corresponding grants.gov page for an opportunity they find on simpler.grants.gov via link on the search results or opportunity listing page ### Proposed metrics for measuring goals/value/definition of done -1. TODO +1. Total number of searches made via the UI +2. Total number of searches made via the API +3. Number of results returned per search +4. Frequency distribution of keyword search terms +5. Frequency distribution of field-based filters +6. Click conversion rate from search results to opportunity listing page ### Destination for live updating metrics @@ -100,7 +143,7 @@ What functionality do we expect to be in place by ***the end*** of work on this - **[Incident Response](https://github.com/HHS/grants-equity/issues/373):** Ensures that we have a robust incident response plan in place when simpler.grants.gov services are interrupted - **[Search API](https://github.com/HHS/grants-equity/issues/90):** Enables system-to-system users to access the search features through the API - **[Search Page](https://github.com/HHS/grants-equity/issues/576):** Enables all other users to access the search features through the user interface -- **[Opportunity Listing Page](https://github.com/HHS/grants-equity/issues/277):** Displays basic information about a given funding opportunity accessed from the search page +- **[Opportunity Listing Page](https://github.com/HHS/grants-equity/issues/277):** Displays basic information about a given funding opportunity accessed from the search page. **Note:** This is a stretch goal for this deliverable and may be substituted with a direct link to the grants.gov page for a given opportunity from the search results. - **[User Research Incentives](https://github.com/HHS/grants-equity/issues/84):** Enables us to engage stakeholders for user testing of the new search functionality Is there any notable functionality we do ***not*** expect to be in place before works starts on this deliverable? @@ -134,8 +177,12 @@ The following work will *not* be completed as part of this deliverable: *Does this milestone involve delivering any content that needs translation?* +TODO + *If so, when will English-language content be locked? Then when will translation be started and completed?* +TODO + ### Services going into PROD for the first time From dee37091db8c73819e9c84f8f6e7a958e6e0fae9 Mon Sep 17 00:00:00 2001 From: Billy Daly Date: Mon, 16 Oct 2023 10:11:10 -0400 Subject: [PATCH 06/19] feat: Add 508 compliance to Definition of Done --- documentation/milestones/individual_milestones/search_mvp.md | 1 + 1 file changed, 1 insertion(+) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index 1bcc81987..a08113c6f 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -98,6 +98,7 @@ The secondary page we want to deliver within the user interface (UI) is an oppor - [ ] Services are live in PROD (may be behind feature flag) - [ ] Translations are live in PROD (if necessary) - [ ] All new services have passed a security review (if necessary) + - [ ] All new services have completed a 508 compliance review (if necessary) - [ ] Data needed for metrics is actively being captured in PROD - [ ] Key architectural decisions made about this deliverable are documented publicly - [ ] Functional requirements: From 3216ac1b4d760685f80fff8d85663776e6242fed Mon Sep 17 00:00:00 2001 From: Billy Daly Date: Mon, 30 Oct 2023 17:28:18 -0400 Subject: [PATCH 07/19] Apply suggestions from code review Updating spec with Sumi's suggestions Co-authored-by: Sumi <111455374+sumiat@users.noreply.github.com> --- documentation/milestones/individual_milestones/search_mvp.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index a08113c6f..602d79e13 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -14,7 +14,7 @@ ## Short description -- **What:** Launch a minimum viable search feature for Simpler Grants.gov that allows users to filter and sort funding opportunities by *at least* one field and by keywords. +- **What:** Soft launch a minimum viable search feature for Simpler Grants.gov that allows users to filter and sort funding opportunities by *at least* one field and by keywords. - **Why:** Proves the successful integration of front-end and backend systems in production and delivers basic search functionality that we can begin to leverage for user testing - **Who:** Targeted group of external stakeholders with whom we'd like to conduct user research and testing @@ -209,7 +209,7 @@ Are there any fields being shared publicly that have never been shared in PROD b ### Security considerations -Does this milestone expose any new attack vectors or expand the attack surface of the product? +Does this 30k ft deliverable expose any new attack vectors or expand the attack surface of the product? 1. TODO From 58468d3461ceeea939764c24c6a9cccbfee906c3 Mon Sep 17 00:00:00 2001 From: Billy Daly Date: Tue, 31 Oct 2023 14:40:24 -0400 Subject: [PATCH 08/19] refactor: updates search_mvp.md - Removes Opportunity Listing as one of the requirements for Search MVP - Indicates that we'll be sharing metrics in GitBook until we deliver a public measurement dashboard --- .../individual_milestones/search_mvp.md | 25 ++++++------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index 602d79e13..d0d4f7114 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -46,7 +46,7 @@ By contrast, this MVP version of search ***does not*** attempt to: - The search functionality to be outlined in the API docs, so that I don't have to rely on experimentation to learn how to search for opportunities. - As a **prospective applicant**, I want: - To be able to be able to search with filters applied, so that the only search results returned are ones that match both the keyword and field-based criteria I specified - - The opportunity listing page to have a link to apply on grants.gov, so that I don't have to repeat my search on grants.gov after finding an opportunity I want to apply for on simpler.grants.gov + - The search results to have a link to the opportunity on grants.gov, so that I don't have to repeat my search on grants.gov after finding an opportunity I want to apply for on simpler.grants.gov - To receive an incentive if I participate in user research for simpler.grants.gov, so that I am fairly compensated for the time that I invest in testing out new features and answering questions - Filters and search terms to be added to the url, so that I can save or share the link to a particular set of search results - As a **project maintainer**, I want: @@ -80,16 +80,6 @@ The primary page we'll need to deliver for the user interface (UI) is a search p - View a common set of fields for each opportunity returned by the search (e.g. title, award date, summary, etc.) - Sort the set of results returned by *at least* one structured field (e.g. award date, title, etc.) -### Opportunity Listing Page - -The secondary page we want to deliver within the user interface (UI) is an opportunity listing page, which should: - -- Display a consistent list of metadata about each opportunity -- Use only fields that are available in the existing grants.gov cloud database -- Link to the corresponding opportunity in the existing grant.gov interface - -**Note:** This is a stretch goal for this deliverable and may be substituted with a direct link to the grants.gov page for a given opportunity from the search results. - ### Definition of done @@ -107,7 +97,7 @@ The secondary page we want to deliver within the user interface (UI) is an oppor - [ ] Users can sort search results by *at least* one structured field (e.g. award date, title, etc.) - [ ] All of the search features available in the UI are also available via the API, and vice versa - [ ] Search criteria are reflected in the URL so that users can bookmark or share the link to a given set of search results - - [ ] Users can access the corresponding grants.gov page for an opportunity they find on simpler.grants.gov via link on the search results or opportunity listing page + - [ ] Users can access the corresponding grants.gov page for an opportunity they find on simpler.grants.gov via link on the search results ### Proposed metrics for measuring goals/value/definition of done @@ -115,13 +105,15 @@ The secondary page we want to deliver within the user interface (UI) is an oppor 1. Total number of searches made via the UI 2. Total number of searches made via the API 3. Number of results returned per search -4. Frequency distribution of keyword search terms -5. Frequency distribution of field-based filters -6. Click conversion rate from search results to opportunity listing page +4. Number of searches made per search term +5. Number of searches made per filter combination +6. Click conversion rate from search results to the opportunity listing (on grants.gov) ### Destination for live updating metrics +Page on the public wiki. **Note:** This will likely change once we deliver the [Public Measurement Dashboard milestone](https://github.com/HHS/grants-equity/issues/65) + ## Planning ### Assumptions & dependencies @@ -144,7 +136,6 @@ What functionality do we expect to be in place by ***the end*** of work on this - **[Incident Response](https://github.com/HHS/grants-equity/issues/373):** Ensures that we have a robust incident response plan in place when simpler.grants.gov services are interrupted - **[Search API](https://github.com/HHS/grants-equity/issues/90):** Enables system-to-system users to access the search features through the API - **[Search Page](https://github.com/HHS/grants-equity/issues/576):** Enables all other users to access the search features through the user interface -- **[Opportunity Listing Page](https://github.com/HHS/grants-equity/issues/277):** Displays basic information about a given funding opportunity accessed from the search page. **Note:** This is a stretch goal for this deliverable and may be substituted with a direct link to the grants.gov page for a given opportunity from the search results. - **[User Research Incentives](https://github.com/HHS/grants-equity/issues/84):** Enables us to engage stakeholders for user testing of the new search functionality Is there any notable functionality we do ***not*** expect to be in place before works starts on this deliverable? @@ -168,8 +159,8 @@ TODO The following work will *not* be completed as part of this deliverable: - **Personalization:** Because the MVP will not support a login experience, any personalized features that require authentication (e.g. saving searches) are explicitly descoped from this deliverable. +- **Opportunity Listing Page:** The MVP will not include an opportunity listing page, instead the search results will directly link to the corresponding opportunity listing page on grants.gov. An updated opportunity listing page will be completed in its own 30k ft deliverable. - **Full Text Search:** The MVP is only expected to include (a subset of) filtering based on opportunity metadata that is already available in the existing grants.gov database, so searching the full text of the opportunity is explicitly descoped from this deliverable. -- **Full Text Listing:** Similarly, the first iteration of the opportunity listing page delivered is only expected to include opportunity fields that are already available in the existing grants.gov database. As a result, displaying the full text of the opportunity within the listing page is explicitly descoped from this deliverable. ## Integrations From fe7162d41ff073feb3388dbdb65bd96f97aab431 Mon Sep 17 00:00:00 2001 From: Sumi <111455374+sumiat@users.noreply.github.com> Date: Fri, 3 Nov 2023 09:54:59 -0700 Subject: [PATCH 09/19] Update documentation/milestones/individual_milestones/search_mvp.md --- documentation/milestones/individual_milestones/search_mvp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index d0d4f7114..f6abd197a 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -173,7 +173,7 @@ TODO *If so, when will English-language content be locked? Then when will translation be started and completed?* -TODO +The translations process will be determined in the 30k ft deliverable: Static Site Public Launch. ### Services going into PROD for the first time From d3713951401541d78ffa72fb4ea0aa9e18c6184a Mon Sep 17 00:00:00 2001 From: Sumi <111455374+sumiat@users.noreply.github.com> Date: Fri, 3 Nov 2023 15:40:32 -0700 Subject: [PATCH 10/19] Update documentation/milestones/individual_milestones/search_mvp.md --- documentation/milestones/individual_milestones/search_mvp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index f6abd197a..d4ee8ab33 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -169,7 +169,7 @@ The following work will *not* be completed as part of this deliverable: *Does this milestone involve delivering any content that needs translation?* -TODO +The translation process will be determined in the 30k ft deliverable in Public Launch: Static Site. *If so, when will English-language content be locked? Then when will translation be started and completed?* From 173ef83b24f9404b0df8bf2986a728c8edb02f83 Mon Sep 17 00:00:00 2001 From: Sumi <111455374+sumiat@users.noreply.github.com> Date: Fri, 3 Nov 2023 15:40:44 -0700 Subject: [PATCH 11/19] Update documentation/milestones/individual_milestones/search_mvp.md --- documentation/milestones/individual_milestones/search_mvp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index d4ee8ab33..07ca36fc4 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -86,7 +86,7 @@ The primary page we'll need to deliver for the user interface (UI) is a search p - [ ] Basic requirements: - [ ] Code is deployed to `main` & PROD through our CI/CD pipeline - [ ] Services are live in PROD (may be behind feature flag) - - [ ] Translations are live in PROD (if necessary) + - [ ] Simpler site translations are live in PROD (if necessary). Translations of the search results content coming from grants.gov will not be included in this 30k ft deliverable. - [ ] All new services have passed a security review (if necessary) - [ ] All new services have completed a 508 compliance review (if necessary) - [ ] Data needed for metrics is actively being captured in PROD From a900ac2703faac3a0bb99574589cb25f13b159ed Mon Sep 17 00:00:00 2001 From: Sumi <111455374+sumiat@users.noreply.github.com> Date: Fri, 3 Nov 2023 15:44:11 -0700 Subject: [PATCH 12/19] Update documentation/milestones/individual_milestones/search_mvp.md --- documentation/milestones/individual_milestones/search_mvp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index 07ca36fc4..2282400d2 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -195,7 +195,7 @@ Are there multiple services that are being connected for the first time in PROD? Are there any fields being shared publicly that have never been shared in PROD before? -1. TODO +The search data and text will be shared for the first time on the site. ### Security considerations From b74c879a6e41e42fb173817cdc8773879f79c521 Mon Sep 17 00:00:00 2001 From: Sumi <111455374+sumiat@users.noreply.github.com> Date: Fri, 3 Nov 2023 15:44:21 -0700 Subject: [PATCH 13/19] Update documentation/milestones/individual_milestones/search_mvp.md --- documentation/milestones/individual_milestones/search_mvp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index 2282400d2..098795479 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -206,4 +206,4 @@ Does this 30k ft deliverable expose any new attack vectors or expand the attack If so, how are we addressing these risks? -1. TODO +We plan to complete a security review and set up any mitigation strategies as needed. From 40726c140d54ac68216b81d85e0759dfb1ec5e7a Mon Sep 17 00:00:00 2001 From: Sumi <111455374+sumiat@users.noreply.github.com> Date: Fri, 3 Nov 2023 15:44:31 -0700 Subject: [PATCH 14/19] Update documentation/milestones/individual_milestones/search_mvp.md --- documentation/milestones/individual_milestones/search_mvp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index 098795479..3c8a8c9a5 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -202,7 +202,7 @@ The search data and text will be shared for the first time on the site. Does this 30k ft deliverable expose any new attack vectors or expand the attack surface of the product? -1. TODO +We're exposing new endpoints that are all read-only this limits vulnerabilities. If so, how are we addressing these risks? From ae05dcc2e62b6ab09a723fa857432e3059259496 Mon Sep 17 00:00:00 2001 From: Sumi <111455374+sumiat@users.noreply.github.com> Date: Fri, 3 Nov 2023 15:45:28 -0700 Subject: [PATCH 15/19] Update documentation/milestones/individual_milestones/search_mvp.md --- documentation/milestones/individual_milestones/search_mvp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index 3c8a8c9a5..6df7b4281 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -147,7 +147,7 @@ Is there any notable functionality we do ***not*** expect to be in place before #### Does the metadata and the text of the opportunity need to be translated? -TODO +We will determine if individual fields from the search results can be easily translated in this effort but opportunity listings and all search results will not be translated in this 30k ft deliverable. #### What metadata is currently available about each opportunity? From 6ede57fedb6de3fe0fa74b32a6295412bf77e609 Mon Sep 17 00:00:00 2001 From: Sumi <111455374+sumiat@users.noreply.github.com> Date: Fri, 3 Nov 2023 15:50:33 -0700 Subject: [PATCH 16/19] Update documentation/milestones/individual_milestones/search_mvp.md --- documentation/milestones/individual_milestones/search_mvp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index 6df7b4281..2dc5230ec 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -151,7 +151,7 @@ We will determine if individual fields from the search results can be easily tra #### What metadata is currently available about each opportunity? -TODO +Metadata is being determined in the GET Opportunity 30k deliverable. We plan to use publicly available data only. For example, is_draft state will not be used in this Search feature. ### Not doing From 7d8b9bda9884e9d3ebb4d3afc481e7ffbee7c8f0 Mon Sep 17 00:00:00 2001 From: Billy Daly Date: Tue, 7 Nov 2023 12:28:47 -0500 Subject: [PATCH 17/19] Update search_mvp.md - Links to deliverable tickets where relevant - Cleans up formatting of sections with questions and answers --- .../individual_milestones/search_mvp.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/milestones/individual_milestones/search_mvp.md index 2dc5230ec..ded53eb05 100644 --- a/documentation/milestones/individual_milestones/search_mvp.md +++ b/documentation/milestones/individual_milestones/search_mvp.md @@ -141,17 +141,18 @@ What functionality do we expect to be in place by ***the end*** of work on this Is there any notable functionality we do ***not*** expect to be in place before works starts on this deliverable? - **AuthN/AuthZ:** Authentication (AuthN) and Authorization (AuthZ) will be the focus of a subsequent deliverable, so the MVP is not expected to support any features that require users to be logged in. +- **Translating text of the NOFOs:** We will not be translating the full text of the NOFO as part of this or future deliverables. ### Open questions #### Does the metadata and the text of the opportunity need to be translated? -We will determine if individual fields from the search results can be easily translated in this effort but opportunity listings and all search results will not be translated in this 30k ft deliverable. +We will determine if individual fields from the search results can be easily translated in this effort but opportunity listings and all search results will _**not**_ be translated in this 30k ft deliverable. #### What metadata is currently available about each opportunity? -Metadata is being determined in the GET Opportunity 30k deliverable. We plan to use publicly available data only. For example, is_draft state will not be used in this Search feature. +Metadata is being determined in the [GET Opportunity 30k deliverable](https://github.com/HHS/simpler-grants-gov/issues/70). We plan to use publicly available data only. For example, `is_draft` state will not be used in this Search feature. ### Not doing @@ -169,11 +170,11 @@ The following work will *not* be completed as part of this deliverable: *Does this milestone involve delivering any content that needs translation?* -The translation process will be determined in the 30k ft deliverable in Public Launch: Static Site. +The translation process will be determined within the [static site public launch deliverable](https://github.com/HHS/simpler-grants-gov/issues/568). *If so, when will English-language content be locked? Then when will translation be started and completed?* -The translations process will be determined in the 30k ft deliverable: Static Site Public Launch. +The translation process will be determined within the [static site public launch deliverable](https://github.com/HHS/simpler-grants-gov/issues/568). ### Services going into PROD for the first time @@ -193,17 +194,17 @@ Are there multiple services that are being connected for the first time in PROD? ### Data being shared publicly for the first time -Are there any fields being shared publicly that have never been shared in PROD before? +_Are there any fields being shared publicly that have never been shared in PROD before?_ The search data and text will be shared for the first time on the site. ### Security considerations -Does this 30k ft deliverable expose any new attack vectors or expand the attack surface of the product? +_Does this 30k ft deliverable expose any new attack vectors or expand the attack surface of the product?_ We're exposing new endpoints that are all read-only this limits vulnerabilities. -If so, how are we addressing these risks? +_If so, how are we addressing these risks?_ We plan to complete a security review and set up any mitigation strategies as needed. From 965f6a8fba10966c50a989769457a661a7f10511 Mon Sep 17 00:00:00 2001 From: widal001 Date: Mon, 20 Nov 2023 15:11:51 -0500 Subject: [PATCH 18/19] refactor: Renames search_mvp deliverable spec The milestones directory was renamed deliverables this moves the spec to the new folder --- .../individual_deliverables}/search_mvp.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename documentation/{milestones/individual_milestones => deliverables/individual_deliverables}/search_mvp.md (100%) diff --git a/documentation/milestones/individual_milestones/search_mvp.md b/documentation/deliverables/individual_deliverables/search_mvp.md similarity index 100% rename from documentation/milestones/individual_milestones/search_mvp.md rename to documentation/deliverables/individual_deliverables/search_mvp.md From 0a05c4a125042018476cf6e64e3418b935b1fcee Mon Sep 17 00:00:00 2001 From: widal001 Date: Mon, 20 Nov 2023 15:19:26 -0500 Subject: [PATCH 19/19] fix: Incorporates PR feedback - Completes unfinished sentence - Removes an unclear "(if necessary)" from acceptance criteria - Fixes a typo in the acceptance criteria - Updates terminology in the summary table at the top of the page --- .../individual_deliverables/search_mvp.md | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/documentation/deliverables/individual_deliverables/search_mvp.md b/documentation/deliverables/individual_deliverables/search_mvp.md index ded53eb05..1be6dae41 100644 --- a/documentation/deliverables/individual_deliverables/search_mvp.md +++ b/documentation/deliverables/individual_deliverables/search_mvp.md @@ -1,14 +1,14 @@ # Search MVP -| Field | Value | -| --------------- | ---------------------------------------------------------- | -| Document Status | Completed | -| Epic Link | [Issue 89](https://github.com/HHS/grants-equity/issues/89) | -| Epic Dashboard | [Product Roadmap](https://github.com/orgs/HHS/projects/12) | -| Product Owner | Lucas Brown | -| Document Owner | Billy Daly | -| Lead Developer | Aaron Couch | -| Lead Designer | Andy Cochran | +| Field | Value | +| ------------------ | ---------------------------------------------------------- | +| Document Status | Completed | +| Deliverable ticket | [Issue 89](https://github.com/HHS/grants-equity/issues/89) | +| Roadmap dashboard | [Product roadmap](https://github.com/orgs/HHS/projects/12) | +| Product owner | Lucas Brown | +| Document owner | Billy Daly | +| Lead developer | Aaron Couch | +| Lead designer | Andy Cochran | ## Short description @@ -62,7 +62,7 @@ The ability to search and filter opportunities should be provided through an API - Search the list of opportunities with open ended key words - Filter the search results by *at least* one structured field (e.g. award date, opportunity type, etc.) -- Sort the search results based on the value of *at least* +- Sort the search results based on the value of *at least* one structured field (e.g. award date, title, etc.) Through the design and development of this API endpoint, the team should answer the following questions and record the decisions in one or more ADRs: @@ -85,8 +85,8 @@ The primary page we'll need to deliver for the user interface (UI) is a search p - [ ] Basic requirements: - [ ] Code is deployed to `main` & PROD through our CI/CD pipeline - - [ ] Services are live in PROD (may be behind feature flag) - - [ ] Simpler site translations are live in PROD (if necessary). Translations of the search results content coming from grants.gov will not be included in this 30k ft deliverable. + - [ ] Services are live in PROD (maybe behind feature flag) + - [ ] Simpler site translations are live in PROD. Translations of the search results content coming from grants.gov will not be included in this 30k ft deliverable. - [ ] All new services have passed a security review (if necessary) - [ ] All new services have completed a 508 compliance review (if necessary) - [ ] Data needed for metrics is actively being captured in PROD @@ -109,6 +109,8 @@ The primary page we'll need to deliver for the user interface (UI) is a search p 5. Number of searches made per filter combination 6. Click conversion rate from search results to the opportunity listing (on grants.gov) +**Note:** While not in scope for this deliverable, we may want to track the accuracy of search results based on user feedback in the future. + ### Destination for live updating metrics