Merge pull request #1158 from cal-itp/portfolio_template

Refactor Summer 2024: Portfolio README.md Template

portfolio/portfolio.py

@@ -310,6 +310,7 @@ def index(
     prod: bool = False,
 ) -> None:
     sites = []
+    Path("/portfolio/index").mkdir(parents=True, exist_ok=True)
     for site in os.listdir("./portfolio/sites/"):
         with open(f"./portfolio/sites/{site}") as f:
             name = site.replace(".yml", "")

portfolio/template_README.md

@@ -0,0 +1,40 @@
+# Purpose of this Template
+To create uniformity across our [portfolio](https://analysis.calitp.org/), here is a template that outlines suggested sections that your website's `README.md` could cover. Adjust the template as you see fit. <b>Delete this verbiage after you are done populating the template and are ready to publish.</b> 
+
+# Title of Your Project
+Outline why you pursued this project.
+* What research question(s) and topic(s) does your work address? 
+* What is the intent of your work? 
+* Why is this relevant?
+* Who is the intended audience for this product? 
+* How do you intend for the stakeholders to use it? 
+* What is the impact your research will have?
+* How often is this website updated with new data? Monthly/quarterly/annually? 
+* Add a link to the folder that houses your code. 
+
+## Definitions
+The narrative portion of your work can contain terms that are unclear. For example, what does <i>peak and off-peak hours</i> mean? Or <i>early, late, and on-time</i>? Although <i>MPO</i> is easily searched, perhaps that can benefit from being defined.
+
+## Methodology
+Detail the analytical decisions you made for your work. What did you do? How did you do it? Why did you approach your work a certain way? Here are some questions that will provide some food for thought. 
+
+* What datasets did you use? 
+* Why did you choose these datasets? 
+* Where did these datasets come from? 
+* What aggregations did you do on your datasets? Why did you choose this particular grain? 
+* What were the steps you took to get to your results?
+* Why did you choose a particular date/time period? 
+* Why did you choose the metrics you did? How did you calculate your metrics? 
+
+## Frequently Asked Questions
+If you foresee that there will be parts of your work that will spark some questions and curiosity from people viewing your work, you can add these potential questions to this FAQ portion. You can also add your contact information if you anticipate questions. 
+
+## Data Sources
+Use this section to send users to the appropriate links to download/view the data you used to create your websites. If the methodology section above doesn't apply to your website, you can write about the data sources you used here. Below is some language you can use, if the data is uploaded to our public GCS folder. 
+
+To download the data that powers this website, please navigate to the folder titled `insert folder name, keep the back ticks` [here](insert link here). You will find the most recent datasets available in `insert the file extensions available` formats. We renamed some of the column names for readability and you can match the [readable column names](insert link to readable.yml) to the original column names. 
+
+## Who We Are
+We want our audience to understand who we are and why our expertise and research should be trusted. Here is a blurb you can lift. 
+
+This website was created by the [California Department of Transportation](https://dot.ca.gov/)'s Division of Data and Digital Services. We are a group of data analysts and scientists who analyze transportation data, such as General Transit Feed Specification (GTFS) data, or data from funding programs such as the Active Transportation Program. Our goal is to transform messy and indecipherable original datasets into usable, customer-friendly products to better the transportation landscape. For more of our work, visit our [portfolio](https://analysis.calitp.org/).