Giter Site home page Giter Site logo

usds / justice40-tool Goto Github PK

View Code? Open in Web Editor NEW
130.0 23.0 42.0 209.42 MB

A tool to identify disadvantaged communities due to environmental, socioeconomic and health burdens

Home Page: https://screeningtool.geoplatform.gov/

License: Creative Commons Zero v1.0 Universal

Python 28.40% JavaScript 1.18% TypeScript 22.51% SCSS 3.24% Jupyter Notebook 44.26% Dockerfile 0.08% Gherkin 0.24% HTML 0.02% Shell 0.07%
open-source environmental-justice climate-change

justice40-tool's People

Contributors

ahlusar1989 avatar dependabot[bot] avatar emma-nechamkin avatar esfoobar-usds avatar ginabeena avatar kameronkerger avatar katherinedm-usds avatar lscharen avatar lucasmbrown-usds avatar mattbowen-usds avatar nathillardusds avatar rohitmusti avatar sampowers-usds avatar saran-ahluwalia avatar stevenlafl avatar sverchdotgov avatar switzersc-usds avatar tomnusds avatar travis-newby avatar vim-usds avatar vincentlausds avatar widal001 avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

justice40-tool's Issues

As an EVCM previewing the tool, I want to see real data represented so that I get a valid sense of how this tool will prioritize my community

Description
This user story is about using real data so in early user research with EVCM participants we can get a sense of how they interact with the live map and datasets, and consequently how they experience seeing the scoring and prioritized communities based on that data.

It's very likely that we won't know what data and map views will be most interesting to particular EVCM people ahead of time, and so seeing how they click/select/interact will be useful user data for us to inform priorities for the end-July version of CEJST.

Solution

  • We likely need to have an eng/product/UX discussion looking at what data sets seem to be the easiest and highest confidence to incorporate at first, as well as which indicators are going to be the most interesting to EVCM
  • Then, we have to identify a doable subset for the very first CEJST version for user testing. This number can really be small, as few as 3 indicators but I could definitely see the value in there being more, 5-10 or so.
  • Transparency in the data, meaning that a reference in the CEJST itself should be viewable for the data set (provenance, year, etc) or it's something we can easily explain or email

Describe alternatives you've considered

  • Static mockups, but this wouldn't let us use early EVCM interaction as a means of learning what data sets are most important and edge cases/gotchas to using the data

Links to user research or other resources
User journey board https://app.mural.co/t/kameronkerger2998/m/kameronkerger2998/1619097401497/d8d8b090c94770d1d72c9c250db564b37676cc69

Definition of "Done"
Live data is incorporated for at least three indicators in early version of CEJST

(Epic) Score comparison tool

As a J40 team member, I want to know how our initial score compares to other industry indicators/scores.

Dependency:

  • Running this tool with actual data requires a current version of the CEJST score to exist.

Definition of done:

  • We've defined which indices/data sets we will initially use for comparison against the current version of the CEJST score
  • We've loaded data from those comparison indices/data sets
  • We have a script or Notebook that creates a report comparing the current version of the CEJST to various indices/data sets

Demo of Done:

  • Prepare a report for internal use about the results of comparisons of the current version of the CEJST score to various stakeholders.

Not doing:

  • Not trying to plan or build cloud infrastructure, i.e. it runs locally.

Tickets to be created:

Below this line are details that will be moved to other tickets shortly.

Description

As we develop a score, we want to understand how are score deviates or stays consistent with other scores used by communities, researchers, and policymakers.

Solution
Initially we want to spike on what's available and possible for an automated comparison tool. We want to get to a place where we have a card in the backlog addressing the following:

It would be ideal to have an open source script that we can run to compare a given census block group score calculated by our tool with a score for that group by another tool or scoring system. This script would have documentation for open source community members to be able to reuse, and we could write updates about this on our website. Ideally, we are able to incorporate this into the tool somehow so that users can also see how this compares to other scores they may be using. This would be a future user story based on further user research.

Ideally, the tool would generate an automated report each time it's run, so that we can continue to use this each time we generate an updated score.

The report can compare two binary scores, such as "the top 25% of SVI communities" compared to "the top 25% of our custom score", and generate a list of census block groups that are in the former but not the latter, as well as a vice versa (a list of CBGs that are that are in the latter but not the former).

The report can also show CBGs where the difference between two scores is the highest. (E.g., a CBG that's much higher on SVI than it is on the current custom score, and vice versa.)

This would require the output of other tools to be consumable data, eg as CSV.

Describe alternatives you've considered

  • Eyeball other scores: This would not be very rigorous or quantitative approach to understanding how our score differs from others.

Links to user research or other resources

Tasks

  • Identify what other scores we wish to compare ours to: Calenviroscreen, R/ECAP, Maryland Score
  • Identify which tools have consumable data that we can use to compare our output with

Definition of "Done"

  • We understand what it will take to write a reusable tool to compare our score against the identified scores with multiple census block groups across the country
  • New card for the comparison tool requirements

As a member of the public, I want to know that our site is a work in progress, so I can set appropriate expectations

Description
We need to let people know that our site is a work in progress

Solution
Let's put a large, visible banner (maybe with construction GIF?) to flag that our github pages site is still in progress

Describe alternatives you've considered

  • If people find this site and don't have context, they may assume it is done already

Links to user research or other resources

  • Under Construction

Tasks

  • Add banner to the github pages site

Definition of "Done"

  • It is obvious to a random person on the team who checks that this is a work in progress

(Epic) Initial Dataset and score

Description

In order to get our data processing and scoring pipelines setup, we should prioritize identifying 2-3 datasets, processing them, and combining them into a score.

Non-goals

This will not include a UI for now, just a mapping from census block group to score

Definition of Done:

  • Initial datasets chosen
  • Command-line tool to show score for a given block group
  • Every census block group in the US has a score its constituent parts

As a developer, I want to understand and document tile hosting options, so that I can make an informed decision about how to vend map data

Description
We should do time-boxed research/have time-boxed discussions about which tile server to use based on the features we need.

Solution
Create an ADR based on outcome of research for a path forward with a tileserver.

Describe alternatives you've considered

  • Need to research alternatives further to give a good list here
  • Another alternative is a fully-custom tileserver backend, but it seems there are a number of options that have a number of features.

Tasks

  • Document tileserver needs
  • Research tileserver options
  • Have conversations about available options
  • Create ADR documenting decision
  • Create followup ticket to handle implementing this solution

Definition of "Done"

  • Merged ADR
  • New ticket for implementation

As experience validated community member (EVCM) I want to be able to print a PDF of the tool so I can use it in reports

Description
This user story is an example of how an EVCM may incorporate CEJST into their own advocacy work. For instance, the EVCM might find a zoom level and/or combination of layers on the CEJST that provides a compelling data case for their community getting specific funding for some remediation project.

This is not the main use case for CEJST obviously or the highest priority, but still, ideally we'd make it easy for our EVCMs to incorporate how they uniquely use CEJST into how they perform their community outreach and advocacy work, and also drive more awareness around CEJST at the same time.

Solution

  • The ability when visiting CEJST to grab a screenshot or generate print view that shows the map at whatever zoom level is selected as well as indicators that are selected, as well as a title/reference to CEJST and Justice40

Describe alternatives you've considered
N/A

Links to user research or other resources
User journey board https://app.mural.co/t/kameronkerger2998/m/kameronkerger2998/1619097401497/d8d8b090c94770d1d72c9c250db564b37676cc69

Definition of "Done"
We get initial feedback from a small number of EVCM stakeholders that they could see easily incorporating snapshots of the tool into presentation materials and reports that they prepare and cite it (i.e. cite version 1.0 or some subsequent verion)

[SPIKE] As a J40 team member, I want to add content to the website without updating HTML, so that I can update content quickly.

Description
We need to enable static site content updates by non-technical team members so that they can keep the website up to date.

Note that there are some uncertainties, hence this being a spike for now. Look into what is possible and what tradeoffs are. Adding markdown support may be straightforward and worthwhile, or it could be a major PIA.

Solution
The minimum viable option would be to enable markdown content on the site; ideally we integrate with a CMS so that team members have a better and more robust content management experience.

Describe alternatives you've considered
Analysis of alternatives for static sites will be available in #6 (one of the features we consider a requirement is markdown content). Analysis of alternatives for headless CMSes will be available in #7.

Links to user research or other resources

Tasks

Definition of "Done"

  • Justice40 team member who is not a developer contributes content to the live site
  • Justice40 team members responsible for content confirm the content management process works for them

Informational Page

Description

We should spec and create a static page with information about the Justice40 Initiative and information about a feedback loop

As an EVCM previewing the tool, I want to see the map at a national level when I first visit the tool so that the first thing I see is clearly and recognizably is the US

Description
The intent of this user story is to make explicit that when someone loads CEJST the first time, the first thing they see is a national level view as opposed to an empty space or arbitrary space, etc.

Update: We will create a separate ticket to explore the best way to represent Alaska and Hawaii and territories at the national zoom level so that those community members know they are represented even if they are not in the lower 48. Users will still be able to drag over and find these locations in the map populated with data.

Note, it's likely and needs to be confirmed that the federal programs impacted by Justice40 have funding relevant to the five major US territories but that's not needed for initial user research version of CEJST.

Solution

  • First page load shows a national level map (geographic data only)
  • Would be good for initial version of CEJST for user research to show live data on national map for first page load, but if this is difficult to do in the near term for performance, etc. reasons it's open to discussion

Describe alternatives you've considered
N/A

Links to user research or other resources
User journey board https://app.mural.co/t/kameronkerger2998/m/kameronkerger2998/1619097401497/d8d8b090c94770d1d72c9c250db564b37676cc69

Definition of "Done"
When EVCM visits URL for the first time, they see a map of the US with CBG boundaries at an appropriate zoom level

As an open source community member, I want to read open source process docs in my native language, so that I can understand the processes and more effectively contribute.

Description
Juan Parras raised the great point in our kickoff call that we should be translating our process docs (not just our published website) into the languages of communities impacted by this work and whom we want to ensure are included in the open source processes we are building.

Solution
Provide translations of our process documentation in prioritized languages. Spanish at a minimum, and we should identify others needed.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Links to user research or other resources

Tasks

Definition of "Done"
Translations of the following docs:

  • README
  • CONTRIBUTING
  • Code of Conduct
  • Data Roadmap Process
  • Locations in directory structure (i.e. /EN and /ES) created to store .md files
  • Issue templates (e.g. have English and Spanish in the template)

As a J40 team member, I want to see site analytics, so I understand how visitors are using the site.

Description
We need to define what analytics we want to capture from the beginning and set up an analytics tool to do so. We may get some logging and analytics out of the box with our hosting solution, but instrumenting on the client side will give us better insights on our audience and how visitors use the site. Insights will help us answer questions such as, are users in geographies with overburdened communities accessing our site? Is content in one language being accessed more than another?

Solution
Identify and implement an analytics tool on the site. I advocate for using an open source, privacy-oriented tool like Matomo as opposed to Google Analytics, but we would need to sort out hosting for this.

Describe alternatives you've considered

Not having an analytics tool: However, if we can get insights from the outset, we should. It's easier to start out with the right tooling than add later.

Links to user research or other resources

Tasks

Identify what metrics would be most useful to capture about site traffic
Research what tools we're able to use
Pick on that meets our needs and constraints and implement

Definition of "Done"

  • We see how many visitors came to our site on the day of launch (and perhaps answer other questions)
  • Documentation on how others can join this
  • meta tags for SEO?

As an EVCM previewing the tool, I want to see and understand clearly which areas at least at a county level are really bad or not as bad (through use of red=bad, green=good or similar) so that I can know that the tool reflects environmental factors I am knowledgeable about

Description
This user story has to do with the zoom level of the map interaction for the initial CEJST prototype for user research. We don't need it to be census block level of resolution for the visual map zooming, but the CEJST previewer needs to at least zoom 3 levels in from national level.

Solution

  • Zoom button or double-click on map interaction that allows CEJST visitor to zoom approximately from national level to state level or region level (approximately) > state regional level > city or county level. There's a lot of latitude the eng team should have for this, and whatever the simplest implementation that gets roughly at this is fine for the initial version.
  • As the user zooms, labels and landmarks (state borders, etc) should be viewable to orient the user
  • Indicator levels (i.e. red and green zones, etc.) are shown at every zoom level
  • If supporting this for every city/county in the country in the near term is too challenging, we can strategically pick a handful of regions/cities/counties to implement this with

Describe alternatives you've considered

  • Static visual mockup of different zoom levels - those might give a good idea to the previewer what the final site might look like, but would not give us a sense of how they would interact. For instance, what if many EVCMs want to zoom in and out to look at neighboring counties, etc.
  • Enter in a zip code and maps zooms in on that zip code such that there's only one zoom level. We need to discuss that type of interaction more and it would likely need its own user story.

Links to user research or other resources
User journey board https://app.mural.co/t/kameronkerger2998/m/kameronkerger2998/1619097401497/d8d8b090c94770d1d72c9c250db564b37676cc69

Definition of "Done"

  • Ability to zoom in three levels across the map to at least a strategic set of cities/counties to enable effective user research

As a non-engineer community member, I want to suggest a new idea for a dataset, so that I can participate in the data pipeline

Description
We should create a means for non-engineer community members to suggest new ideas for a dataset, using tools familiar to them.

Solution
To make it easy for non-engineer members of the public and advisory bodies such as the WHEJAC to submit suggestions for data sets, we will configure a Google Form that maps to the schema of the data set files. It probably makes the most sense to autogenerate the Google Form out of the Yamale schema for data set descriptions and the accompanying field description file; this will help keep the schema and the Google Form in sync.

This will enable members of the public to fill out a simple form suggesting data without needing to understand Github or other engineering concepts.

At first, these responses can just go into a resulting Google Sheet and be manually copied and converted into data set description files. Later, we can write a script that converts new entries in the Google Sheet automatically into data set file descriptions and opens a pull request. That work is tracked in this ticket

Tasks

  • Setup official Google Sheet with appropriate schema, share publicly
  • Create a Google Form to capture additional responses

Definition of "Done"

  • Sheet created and circulated
  • Form public

Gotchas

  • Ensure we're compliant with PRA restrictions

Decision: As a developer, I want to understand if geoplatform.gov is the best option for data storage for J40.

Description
Now that we have access, we should investigate the geoplatform.gov feature set and determine if it can host our datasets, layers, services, and/or FE code.

Solution
Create ADR for using Geoplatform based on research from team.

Describe alternatives you've considered

  • Cloud.gov
  • Federalist
  • ArcGIS Hub

Links to user research or other resources
Research to be included in ADR

Tasks

  • Meet with Joel @ Geoplatform to understand what abilities our credentials grant us
  • Discuss with him and document available feature sets
  • Identify opportunities for dataset hosting
  • Identify opportunities for layer hosting
  • Identify opportunities for static site hosting
  • Identify opportunities for mvt/tile service hosting

Definition of "Done"

  • We've compiled an ADR that includes the above sections and compares the available options

As an engineer community member, I want to suggest a new idea for a dataset, so that I can participate in the data pipeline

Description
We should create a means for engineer community members to suggest new ideas for a dataset, using tools familiar to them.

Solution
To start, we'll create a folder in the appropriate repository that can house YAML files, one per data set. Each file will describe the characteristics of the data.

We'll use a Python-based script to load all the files in the directory, and then run a schema validator to ensure all the files have valid entries.

For schema validation, we propose using Yamale. This provides a lightweight schema and validator, and integrates nicely with GitHub actions.

If there's an improper format in any of the files, the schema validator will throw an error.

As part of this milestone, we will also set this up to run automatically with each commit to any branch as part of CI/CD.

Describe alternatives you've considered

  • The benefit of using a YAML file for this is that it's easy to subject changes to these files to peer review through the pull request process. This allows external collaborators from the open source community to submit suggested changes, which can be reviewed by the core CEJST team.

Tasks

  • Create directory structure and README
  • Create YAML schema
  • Create schema validator
  • Integrate this process into Continuous Integration
  • Create Github issue template to create new dataset suggestion

Definition of "Done"

  • Pipeline has been run end to end on a new dataset, including CI integration

As a repo contributor, I want to make sure my frontend code passes checks before/after it is merged, so that we maintain a high standard of quality and consistency

Description
We should implement the best practices of continuous integration of source code, meaning performing a series of checks for PRs

Solution
Set up minimal pipelines with a chosen CI tool such as Github Actions/Jenkins/TravisCI that implement the above checks

Describe alternatives you've considered
The alternative is to not perform these checks, which can lead to ruin.

Links to user research or other resources
N/A

Tech Tasks

  • Linting/formatting (eg eslnt, prettier)
  • Security auditing (eg npm audit)
  • License check (eg license-checker)
  • Dependency updating (eg dependabot etc)
  • Container-based unit testing / reporting (eg jest, junit)
  • Integration testing (e.g. puppeteer)
  • Snapshot testing (jest-snapshot, etc)

Definition of "Done"

  • Checks run on every PR
  • We have identified a basic set of tests that run on every PR / Commit and these are running regularly and producing results

As a community member, I want to vote on what data sources should be prioritized next, so that I can have input into the process

Description
This milestone is currently the least well-defined. It's important that members of advisory bodies like the WHEJAC and members of the public be able to "upvote" certain data sets for inclusion in the tool.

Solution
One potential for this is to use the Stanford Participatory Budgeting Platform. Here's an example of voting on proposals within a limited budget.

For instance, going into a quarterly planning cycle, the CEJST development team could estimate the amount of time (in developer-weeks) that it would take to clean, analyze, and incorporate each potential data set. For instance, incorporating some already-cleaned census data may take 1 week of a developer's time, while incorporating new asthma data from CMS that's never been publicly released could take 5 weeks. Given a "budget" of the number of developer weeks available (e.g., 2 developers for 13 weeks, or 26 developer-weeks), advisors can vote on their top priorities for inclusion in the tool within the available "budget".

Links to user research or other resources
https://pbstanford.org/

Tasks

  • Implement voting system of some sort
  • Implement some notion of "budget"

Definition of "Done"

  • All community members have a publicly-available means of voting on datasets

As a developer, I want new data set ideas from non-engineer community members to be automatically submitted as pull requests, so that they can easily be integrated into the data roadmap.

Description
We should create a means for non-engineer community members to suggest new ideas for a dataset, using tools familiar to them.

Solution
To make it easy for non-engineer members of the public and advisory bodies such as the WHEJAC to submit suggestions for data sets, we will configure a Google Form that maps to the schema of the data set files, as description in this ticket. At first, these responses will just go into a resulting Google Sheet and be manually copied and converted into data set description files.

As part of this ticket, we can write a script that converts new entries in the Google Sheet automatically into data set file descriptions and opens a pull request. This can be setup to run as a trigger on the addition of new rows to the Google Sheet.

Alternative means of achieving the same goals are also appropriate!

Tasks

  • Setup a trigger that converts new Google Form entries into data set description YAML files
  • Automatically open a pull request with the new data set description

Definition of "Done"

  • When data set ideas are submitted via Google Forms, they're converted into a pull request against the main repo.

Gotchas

As an EVCM previewing the tool, I want to see the initial version of prioritized community scoring so that I can understand how it works

Description
This user story is about the preview version of the tool to be used for user research having some draft version of scoring methodology for communities. Even if the preview version of the tool only has four (purely arbitrary small number) indicators and the draft scoring methodology has 10% of all census blocks are the top tranche of prioritized blocks based on a 25/25/25/25% split of weightings between the four indicators, this draft scoring methodology combined with some messaging from us to those previewing CEJST that this is just a prototype to help us get feedback, having some early version of a community scoring methodology will help preview visitors conceptualize how indicator data > ranked community list > prioritized community list could work.

Solution

  • Initial list of indicators
  • A "proof of concept" draft equation to combine those particular indicators into a cumulative score
  • transparency around this draft equation (i.e. if someone previewing CEJST wants to know the draft equation, we can easily explain it or email it)
  • Application of those scores to all census and tribal blocks. Or at least some strategically picked smaller regions so that CEJST previewers can see how it works
  • All census and tribal blocks (at least within the strategically picked regions if applicable) are ranked
  • A proof of concept draft version of the logic to pick the "prioritized communities" within this list
  • Early versions of the tool can reference census blocks in the list, but ideally city, county, zip code are mentioned as well

Describe alternatives you've considered

  • Static mockup of scoring model - there might be some value to that, but this particular user story involves CEJST previewers understanding how choice of indicators impacts the scoring.

Links to user research or other resources
User journey board https://app.mural.co/t/kameronkerger2998/m/kameronkerger2998/1619097401497/d8d8b090c94770d1d72c9c250db564b37676cc69

Definition of "Done"
TBD

  • One possible criterion, we get initial feedback from a small number of EVCM stakeholders?

As a community member, I want to understand what this repo is, so that I know how to engage with it.

Description
When someone lands on this public repo, they need to understand what it is, who we are, why we've made this, and how they can interact with this repo or the project.

Solution
Add the standard OSS content:

  • README
  • Contributing.md
  • Code of Conduct
  • License
  • Link to website or other public info about Justice40
  • Info on how to contact us

Describe alternatives you've considered
N/A

Links to user research or other resources
N/A

Tasks

  • set up public listserv

Definition of "Done"

  • List above is complete
  • We have shared the repo with this fresh content with our OSS community

Informational Page

Description

We should spec and create a static page with information about the Justice40 Initiative and information about a feedback loop

As a J40 team member, I want to identify an initial set of datasets to work with so that I can begin setting up the data pipeline.

Description
We need to start figuring out what the nuts and bolts of our data pipeline look like and start piecing them together. This is best done through implementation and learning with a real dataset we may want to use in the product. The goal of this issue is to start getting hands on with data so we can start building out our infrastructure to support the tool's ongoing data roadmap process.

It is important to note that the shortlist of datasets identified in this issue may or may not be in the first release of the tool and score. We will do our best to choose ones we think will be useful in the tool, but will rely on community feedback and guidance from the WHEJAC to make that decision.

Solution
We have a list of 90+ dataset ideas primarily sourced from the WHEJAC as well as from other advisors. We will divide and conquer an initial investigation of this list to identify ones based on the following 4 principles:

  • Resolution is at the census block group level
  • It is recent, preferably under 3 years old
  • It is nationally consistent
  • It is already clean and validated, as well as usable as geospatial data with minimal processing

We will also ensure the initial shortlist of datasets also spans identified categories of environmental, climate, and economic indicators.

We will then implement our data pipeline and a prototype tool with this shortlist. With the prototype we will get community and WHEJAC feedback and decide whether to continue use of these datasets.

Describe alternatives you've considered

Links to user research or other resources

Tasks

  • Find and assess available datasets based on the data ideas list provided by the WHEJAC using the 4 principles abovee

Definition of "Done"

  • 3-5 datasets are identified that meet the 4 principles outlined above and span the categories of indicators the J40 community cares about.

As a developer on the project, I want to understand and easily update our system architecture, so that I can contribute at a high level to the project

Description
We should document our current thinking about project architecture for future reference, in a way that can be updated and evolved over time with community support

Solution
Utilize mermaid.js to setup a pipeline allowing us to create text-based diagrams and render them as images

Describe alternatives you've considered

  • Pure image-based diagrams get out of date and are difficult to version
  • Mural requires an account and does not support versioning

Links to user research or other resources
Mermaid - Mermaid is an excellent text-based tool for creating diagrams

Tasks

  • Document current architecture in Markdown-based Mermaid file
  • Create github actions steps to automate the creation of similar diagrams in the future
  • Document the workflow for future reference in the README
    Definition of "Done"

As a member of the public, I want to see J40's website live on the internet, so that I know it's real!

Description
This one is all about hosting the website!

Solution
Deploy the website with continuous dellivery set up. This will likely be on geoplatform.gov's S3 bucket, pending #18.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Links to user research or other resources

Tasks

  • Secure and set up domain (this may be a Github pages URL as an intermediary while we work on a .gov URL)
  • Set up deployment and deploy

Definition of "Done"

  • I can visit the given URL with an internet connection and see the website live!

As a repo contributor, I want to make sure my data processing code passes checks before/after it is merged, so that we maintain a high standard of quality and consistency

Description
We should implement the best practices of continuous integration of source code, meaning performing the following checks for PRs against our data processing scripts (assumed at this stage to be python-based)

  • Linting/formatting (eg Black, flake8) (potentially pre-commit hook?)
  • Security auditing (eg safety)
  • License check (eg liccheck2)
  • Dependency updating (eg dependabot etc)
  • Container-based unit testing / reporting (eg unittest, pytest, etc)
  • Integration testing (e.g. pytest etc)
  • Package management (e.g. poetry)

Solution
Set up minimal pipelines with a chosen CI tool such as Github Actions/Jenkins/TravisCI that implement the above checks, targeting data processing filepaths

Describe alternatives you've considered
The alternative is to not perform these checks, which can lead to ruin.

Links to user research or other resources
N/A

Tasks

  • Standup basic CI/CD for commits
  • Add the above checks
  • Determine the minimal set of necessary checks out of the gate and potentially create followup issues for the rest

Definition of "Done"

  • Checks run on every PR against data processing scripts
  • We have identified a basic set of tests that run on every PR / Commit and these are running regularly and producing results

As an EVCM previewing the tool, I want to zoom in to the state and county level

Description
This user story has to do with the zoom level of the map interaction for the initial CEJST prototype for user research. We don't need it to be census block level of resolution for the visual map zooming, but the CEJST previewer needs to at least zoom 3 levels in from national level.

Solution

Zoom button or double-click on map interaction that allows CEJST visitor to zoom approximately from national level to state level or region level (approximately) > state regional level > city or county level. There's a lot of latitude the eng team should have for this, and whatever the simplest implementation that gets roughly at this is fine for the initial version.
As the user zooms, labels and landmarks (state borders, etc) should be viewable to orient the user
If supporting this for every city/county in the country in the near term is too challenging, we can strategically pick a handful of regions/cities/counties to implement this with
Describe alternatives you've considered

Static visual mockup of different zoom levels - those might give a good idea to the previewer what the final site might look like, but would not give us a sense of how they would interact. For instance, what if many EVCMs want to zoom in and out to look at neighboring counties, etc.
Enter in a zip code and maps zooms in on that zip code such that there's only one zoom level. We need to discuss that type of interaction more and it would likely need its own user story.
Links to user research or other resources
User journey board https://app.mural.co/t/kameronkerger2998/m/kameronkerger2998/1619097401497/d8d8b090c94770d1d72c9c250db564b37676cc69

Definition of "Done"

Ability to zoom in three levels across the map to at least a strategic set of cities/counties to enable effective user research

As a repo contributor, I want to be able to install and run all code locally, so that I can actively contribute.

Description
This is about making sure internal and external contributors can onboard to the codebase quickly and easily.

Solution

  • Add clear install steps and dependencies to the README.
  • Containerize app so that it's easily portable across machines.

Describe alternatives you've considered
N/A

Links to user research or other resources
N/A

Definition of "Done"

  • A new developer confirms they can get up and running locally with the code base in a container with no support from a team member

Fix robots.txt

Describe the bug
robots.txt file is set to disallow crawling while we're actively developing. Need to fix for production

As a member of the public, I want to learn about Justice40.

Description
We should put up a lightly-styled, representative-content version of our initial site for the sake of forming an informational landing page.

Solution
Following the creation of our static site (#17), we should add some approved content and some basic styling utilizing the US Web Design System.

Describe alternatives you've considered

  • Not posting any content to begin with -- we need to give the public a feel for the messaging and design of our eventual site right out of the gate.

Links to user research or other resources
N/A

General Tasks

  • Get content approved
  • Get translation approved

Tech Tasks

Definition of "Done"

  • We've posted content in English and Spanish
  • We've styled that content appropriately according to a related spec.
  • We have a website we can spin up locally. [This card is not about deploying]

Design Needs

  • Reduced version of site spec (perhaps a limited version of earlier-discussed prototype, with a focus on content and content placement?)

As a developer I need a way to host my code as we develop, so that I can run it from anywhere

Description
We need to setup interim hosting so we are able to run our code from anywhere

Solution
As an initial stab, we should use cloud.gov sandbox for this purpose

Describe alternatives you've considered
Running from one of our machines, but this would require it to always be running; aws, but this would require agency approval

Links to user research or other resources
N/A

Tasks

  • Create hosted pg_tileserv tile server
  • Create hosted static FE site

Definition of "Done"

  • Code is setup and running on cloud.gov sandbox

Analysis of Alternatives: Front end site options

Description
We need to identify what our front end stack is for our informational site and app.

Here are the features we're looking to prioritize on the front end:

  • smooth integration with our map client (open layers)
  • accessibility support
  • responsive
  • fast
  • easy content updates by non-technical team member (in markdown at minimum, ideally with a CMS integration)
  • offline support / usable with low-bandwidth connections
  • can be hosted as a static site, eg Github Pages (this makes deployment and authorization easier esp in short term), but scalable so we can add more interactive, dyanmic app features later as needed
  • support for users wanting to print pages as PDFs
  • support for localization tools
  • use of US Web Design System for styles

Definition of done
Architecture Decision Record created and approved

As a developer who does not speak English as a primary language, I want to be able to understand and contribute to the codebase so that I can participate in the development processes.

Description
Right now, the open source documentation, codebase, and data roadmap is entirely in English. We should explore options for making the documentation, codebase, and data roadmap accessible in other languages, in particular Spanish.

Describe alternatives you've considered
The alternative is to only have the codebase documented in only English, which can exclude people who have important skills and experiences and expertise to contribute to this process who do not use English as a primary language.

Links to user research or other resources
N/A

Tasks

  • ADR for approach to language accessibility in documentation, codebase, and data roadmap

As a developer, I want to know more about OpenLayers, so that I can understand better its performance

Description
We need to better understand: what are the limits of the OpenLayers library? We've heard anecdotally in a few places that these are the particular concerns:
* Developer usability
* Rendering/performance
* Accessibility

Solution
Let's do a short, time-boxed investigation where we tweak specific parameters and get better measurements to better inform our understanding of the library.

Describe alternatives you've considered
We will keep this decision time-boxed, rather than going too far after having chosen a particular tool to go back.

Links to user research or other resources

  • Our current FE tool analysis goes into some detail here but we need to flesh out the particulars and see how they apply to our specific use case.
  • Our current Gatsby branch with an existing Proof Of Concept OpenLayers implementation

Tasks

  • Mapbox styles plugin - does this improve usability / interoperability
  • Research WebGL support : there's a beta that puts back webGL support, also older versions; do these improve things?
  • Measure different combinations of raster / vector
  • Use Chrome DevTools and/or Puppeteer to do a basic render sanity check / comparison
  • Use VoiceOver to test comparative accessibility
  • Understand possible react support / wrappers
  • Understand user interaction difficulty

Definition of "Done"

  • Comparative performance analysis (at least OL + MB)
  • Comparative accessibility analysis (at least OL + MB)
  • Working prototype with above modifications in place
  • Documented WebGL support specifics

As a developer, I want to know what dataset to work on next, so that I can match priorities to those from the community

Description
We should integrate the dataset proposal process with our ticketing system to keep track of work as it progresses.

Solution
For each data set that is being considered for inclusion soon in the tool, the project management team will create a ticket for "Incorporating ___ data set into the database", with a link to the data set detail document. This ticket will be created in the ticket tracking system used by the open source repository, which is ZenHub. This project management system will be public.

At the initial launch, we are not planning for members of the open source community to be able to create tickets, but we would like to consider a process for members of the open source community creating tickets that can go through review by the CEJST team.

This will help developers know what to work on next, and open source community members can also pick up tickets and work to integrate the data sets.

Tasks

  • Setup process by which tickets can be created from approved requests
  • Setup columns and label systems

Open Questions

  • Is this a separate project board?
  • What should the phases be?
  • How can we involve outside assistance in processing datasets (e.g. geoplatform/Zenity)

Definition of "Done"

  • Approved datasets are automatically tracked in issue tracking system

As a community member, I want to understand what happened with my suggestion for a new dataset.

Description
Once suggested, we should have a single place where all community members can go to see the current status of a given dataset request.

Solution
Add a script that runs the schema validator on all files and, if successful, posts the results in a tabular format. There are straightforward packages to post a Python dictionary / pandas dataframe to Google Sheets and/or Airtable. As part of this milestone, we will also set this up to run automatically with each commit to main as part of CI/CD.

This will make it easier to filter the data to answer questions like, "which data sources are available at the census block group level"

Describe alternatives you've considered

  • Doing this in a proprietary tool like ArcGIS hub is not an option given our focus on openness.

Tasks

  • Create a script or Github Actions step that converts validated schemas to rows in a table of some sort
  • Integrate this with the CI/CD pipeline
  • Enable filtering on this dataset

Definition of "Done"

  • Publicly-available table exists
  • Table is populated automatically when new dataset is added

Data Roadmap

Description

We should define the process for the intake, prioritization, and voting on datasets for inclusion in the Justice40 Tool.

Definition of Done

  • Process has been defined
  • We have sent one dataset through the entire process end to end
  • Data pipeline is hosted and publicly accessible

As a WHEJAC board member, I want to track general problem areas or data idea so that I don't have to have a specific dataset in mind

Description
We should add a means of annotating datasets with "problem areas" that describe problems in climate, environmental, and economic justice, in order to allow for higher-level grouping and tracking. This is so that non-data-focused members of the public or the WHEJAC advisory body can suggest we prioritize certain problem areas, with or without ideas for specific data sets that may best address that problem area. For instance, a problem area may be "food insecurity", and a number of data sets can have this as their problem area.

Solution
We should add a field in our dataset description that includes "problem area" in some form.

Open Questions
Still open as to how to do this:

  • Create a folder for descriptions of problem areas, which contains YAML files that get validated according to a schema
  • Add these as an array in the description of data sets
  • Add labels to the tickets once data sets are tracked in GitHub tickets

Tasks

  • Create initial set of labels in some form
  • Change the linter to validate that every data set description maps to one or more known problem areas
  • Enable filtering on these labels in some form

Definition of "Done"

  • We have defined a set of problem area labels
  • Problem area labels are applied to all existing issues

As a open source contributor, I want to know what the license for this software is, so that I can use this code legally.

Description
We need to choose a license for this repo! If I recall correctly, last time around all US Government projects had to be something like Creative Commons 0 -- absolutely no restrictions. But we should check and make a decision.

Solution
The repo contains a LICENSE.

Tasks

  • If necessary, ask other USDS people about what licenses we are able to use.
  • Choose a license.

Definition of "Done"

  • The repo contains a LICENSE.

Decision: As a developer, I want to decide on a frontend mapping library to use, so that we faithfully represent our project values and provide for user needs

Description
We should analyze frontend mapping visualization libraries and decide on one that both represents our project values and provides for our user needs.

Solution
Create an Action Decision Record to represent our decision and explains our reasoning.

Describe alternatives you've considered
An Analysis of Alternatives is a pretty similar idea, but not directly supported via CLI tooling

Links to user research or other resources
This will be informed by:

Tasks

  • Create an Architectural Decision Record about Frontend mapping librareis
  • Decide on initial frontend map visualization framework to use

Definition of "Done"

  • We've fully explored alternatives, given current understanding of requirements
  • We've arrived at a choice that makes sense for now
  • We've documented our findings

ADR: Update ADR process to use Project board

Update ADR process to use Project board

Context and Problem Statement

Our current ADR process is a bit cumbersome. Let's update it by using Github project boards and PRs!

Decision Drivers

  • Using just filenames can result in naming collisions if another ADR is updated first
  • The current "Status" field in the ADR itself can get out of sync with the actual status
  • It is currently necessary to manually copy a template in order to initiate a PR
  • The curent process necessitates email list discussion which can become separate from the decision itself

Considered Options

  • Continuing to use the existing process - this has the above drawbacks
  • Using a different tool to track issues - this would separate the decision from the discussion

Decision Outcome

We have created:

  1. A new project board
  2. A new issue template
  3. A new process for using them, described below, that supersedes the previous process

Chosen option: use github project boards as described below. Reasoning:

  • We only update the file when a decision has been reached, thus avoiding naming conflicts
  • We can use columns in project boards to represent status
  • We can use the built-in issue template mechanism in github to enforce consistency
  • Github offers a built-in discussion feature so we can capture discussion next to where the decision is made

Explanation of new process - to be added as a separate description later (updated diagram also to be posted as a comment here):

  1. Draft: To create a new ADR:

    1. Create a new issue in github or zenhub.
    2. Select the template "Architectural Decision Record".
    3. Select "Project", then "Repository", and set it to "Architecture decision records"
      This will create a new issue, add it to the "Draft" column (to be done via github actions), and assign the core project maintainers to approve
  2. Screenshots/diagrams: If you need to add diagrams or screenshots/pictures, please add them to the comment section of the issue.

  3. Ready for Discussion : The core project maintainers (for now the USDS folks until we have regularized this process) will review - they will:

    1. Add the "Ready for Discussion" label if the issue is well-formed / has enough detail
    2. Move the issue to the "In Discussion" column
    3. Setup a public comment period - this is the period within which we need to come to a decision (more on this below)
  4. In Discussion : Once the item is in the "In Discussion" column, you have until the period specified to come to a decision. People can leave comments directly on the ticket There are several outcomes:

    1. Consensus In the event of consensus within the expressed timeline, move to the next step
    2. Concerns If there are concerns raised, ensure that those that disagree understand the reasoning behind the decision and address concerns with specific mitigation steps. Request confirmation that concerns have been addressed. If so, move to the next step!
    3. Discuss In the event that disagreement persists, discuss the decision with the group in the next biweekly sync. We will take a vote on next steps (opt-outs are OK!), and move forward.
  5. Decided: Once the comment period has elapsed, move the issue to "Decided". This is where the issue will wait before you have created a Pull Request. Please at this time add one of the following labels:

    • "Approved" -- Decision Record has been approved
    • "Rejected" -- Decision Record has been rejected
    • "Superseded" -- Decision Record has been made obsolete by another record (leave in comment) -- please add this to any record your record supersedes.
  6. Pull Request: Once decided, you should create a pull request to create a file in docs/decisions - name it XXXX where XXXX is one greater than the largest decision record in the directory. Copy and paste the record from the issue. As for diagrams and

    1. We recommend Mermaid for diagrams! Create a file with a .mmd extension and reference filename-mmd.svg in your docs, and Github Actions will automatically create the svg fore you! Preview diagrams with the Mermaid Live Editor.
    2. To keep things organized, create a folder with the name XXXX-files and put supporting ADR material there.
  7. Merge: once the PR has been approved, merge and close

Positive Consequences

  • ADRs no longer have the above-named limitations

Negative Consequences

  • We'll need to discuss and socialize these changes.

Pros and Cons of the Options

Leaving as Is

  • Good, because it's maybe a little less involved
  • Bad, because it requires keeping a fragile text file up to date, and separates discussion from decision, and is not as integrated into the process

Another tool

e.g. Trello etc.

  • Good, because there are other tools that are purpose-built to move tickets left -> right
  • Bad, because this is yet another tool we've got to integrate, and it separates discussion from decision again

Links

As an EVCM previewing the tool, when presented with a long list of indicators, I want to be able to adjust the weights or toggle on/off indicators I'm more/less interested in so that I can see how different indicator factors may influence my community

Description
This will enable EVCMs who are user research participants, or the small set of stakeholders who will preview the tool soon, to interact with indicators and see for themselves how that influences a draft community scoring. This in turn will inform the evolution of the datasets used for CEJST (and how we design the data backlog as well).

Solution

  • For early version of CEJST that will be used for user research, each indicator can have a slider (i.e. 0/50/100) or toggle (0/100) that the visitor can change
  • When the user changes the slider/toggle for that indicator, the map view (i.e. red or green zones) changes accordingly
  • At some point when the indicator sliders/toggles are updated, an updated score and prioritized community list is generated. For initial version, this can done dynamically or generated when the user does something like presses an "Update Score" button

Describe alternatives you've considered

  • A static list of indicators would not (1) give CEJST users a sense of control, and (2) would not give us in a tangible way what indicators are important to them

Links to user research or other resources
User journey board https://app.mural.co/t/kameronkerger2998/m/kameronkerger2998/1619097401497/d8d8b090c94770d1d72c9c250db564b37676cc69

Definition of "Done"

  • Functional slider or toggle shown for each indicator shown on CEJST
  • Scoring shown on maps and list of prioritized communities updates, though if this functionality is buggy that's ok for the initial version

As a developer I want to have a static site base to build upon

Description
Following our decision around static site generators (here ), we should create a template based on this framework and commit to the repo for future iteration.

Solution
Use site generator to create scaffolding for a new site.

Describe alternatives you've considered
See #6

Links to user research or other resources
See above

Tasks

  • Generate static site

Definition of "Done"

  • Bare site scaffolding has been committed to the repo
  • Localization framework/tooling set up as relevant

As a developer, I want to limit the audience that sees new features, so that we can control the message and positioning of our tool

Description
We should add some means of limiting the audience for new features, so as to control the visibility of in-progress work while also getting real users to use our software

Solution
Use feature flagging on in-progress work, control through an allow list

Describe alternatives you've considered

  • LaunchDarkly - a very full-featured version of this from the private sector; is there an OS equivalent?
  • Security through obscurity - only sharing the link to certain people is not wise, as the link will get out.

Tasks

  • Add a feature flagging mechanism
  • Use this feature flag for a particular feature
  • Setup an initial audience for the feature

Definition of "Done"

  • We have released a feature to only a subset of our total audience

Open Questions

  • What tool should we use, in keeping with our OSS bent?
  • How should we control the allow list, given we don't have user logins?

As an EVCM, I want to make sure the information I see on the CEJST app matches what I see on the ground, so that I can trust that it represents the ground truth, or at least help it be more accurate

Description
CEJST needs to reflect community members' lived experiences. We need a multi-pronged approach. One major part of the approach includes EJ community members co-designing tool and cumulative impact score through written recos, listening sessions, moderated user research sessions, feedback links in the tool, etc. But an additional way is to incorporate very personalized localized on the ground information from users, such as GPS tagged photos of bad pollution emission. To further illustrate, an EVCM may see that other communities in their county are prioritized ahead of theirs in CEJST, but they can take a photo of bad exhaust emitted near their home, in contrast to blue skies everywhere else they can see. They can provide on the ground data showing pollution uniquely burdening their community that is not reflected in the tool.

(This feature is not MVP, but wanted to get on team's radar sooner rather than later. Has far reaching implications. Might warrant being an epic in itself.)

Solution
From the Justice40 Discovery Sprint Report

In California, where they use cumulative impacts score, they spent countless hours on the ground with and in communities in order to ensure that burdens and other factors were being considered. In some cases, the research team who originally developed scoring methodology upon which their geospatial tool, CalEnviroScreen, was built, would go into communities with preliminary maps and “ground-truth” them, block-by-block allowing community members armed with cell phones to capture pictures and tracked GPS locations to redraw them to more accurately reflect their lived experiences.

One potentially feasible solution would be to ask CalEnviroScreen team if they have recent on the ground information that can be shared with us, and we can see if CEJST visual mapping and scoring accurately represents, and potentially get the team's advice as well.

Describe alternatives you've considered
We could potentially conduct these kind of spot checks ourselves, or ask interested and willing EJ community members to help us with providing on the ground information.

Links to user research or other resources
City 311 apps allow community members to upload GPS tagged photos of incidents, sidewalk cleaning, dumping issues, etc. https://apps.apple.com/us/app/sf311/id666635420 for the purposes of city departments remediating. This also creates a measurable traceable body of community generated information.

Tasks

  • How would we even receive this information? CEJST visitor ability to upload photos, etc?
  • Define and implement how would we ingest and store information, meta data, etc.
  • Define and implement logic to connect on the ground information to community, i.e. census block
  • Define and implement process of review/arbitration of on the ground information and how it impacts how community is represented in app visually and prioritized via cumulative impact score

Definition of "Done"

  • First pilot of community member upload of on the ground information and being shown how information impacts (or will impact) how their community is represented visually in the tool and in cumulative impact score

As a repo contributor, I want to understand how large decisions are made, so that I can contribute to making them myself.

Description
We should propose and document a process for Architecture Decision Records to make it easier to contribute to larger decisions on this project.

Solution
Use a Meta-ADR to document an ADR Process

Describe alternatives you've considered

  • Unilateral Decision-making
  • Not documenting at all

Tasks

  • Create diagram for proposed process
  • Create Pull Request for ADR describing process
  • Email asking feedback

Definition of "Done"

  • ADR describing process has been merged

As a J40 team member, I want to experiment with different ways to combine scores, so that we can arrive at a meaningful aggregate

Description
There are a number of methodologies out there for combining scores into a single indicator - let's understand this a bit better and incorporate them into a proof of concept tool. We want to do a spike on the research for this to create a methodology we can begin doing user research with in our MURT.

Solution
Research, consult, make initial decision

Describe alternatives you've considered
This research will include an analysis of various scoring methods

Links to user research or other resources

Tasks

  • Solicit community and expert feedback
  • Identify a methodology to begin with for user feedback
  • Document or implement this methodology in a non-UI tool (eg in a data notebook or as a command line tool)
  • Test this methodology to ensure it is always consistent

Definition of "Done"

  • We have chosen an initial scoring methodology for user feedback in the MURT
  • We have incorporated the score into our non-UI tool

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.