Skip to main content

README and Repo Hygiene

Why This Matters

A reviewer should not need private instructions to understand the project. The README and file structure are part of the scientific record.

Assume the reader has not taken this course. Your README and portfolio page should explain the project purpose, data source, main result, limitations, and how to reproduce the work.

Good repo hygiene reduces grading friction and makes the final portfolio easier to trust.

README Minimums

The project README should name:

  • project title and audience;
  • project question;
  • data source and access route;
  • folder structure;
  • how to render the report;
  • how to open or run the dashboard-style KT product;
  • package or environment setup;
  • known limitations or risks;
  • public/private sharing status.

Weak vs Strong: A README Example

A weak README tells the reader almost nothing:

# Our Project
Class project for SPPH 381H. Run the code to see the results.

A reviewer who opens this repository does not know what the project asks, where the data comes from, or which file to run.

A strong README answers those questions directly:

# Sleep and Blood Pressure in US Adults (NHANES 2017-2018)

Audience: community health staff planning sleep-screening outreach.
Question: Is short sleep associated with higher blood pressure?
Data: NHANES 2017-2018 public files; see data/README.md for the access route.
Main result: adults reporting under 6 hours of sleep had higher average
  systolic blood pressure; see reports/final-report.html.
Reproduce: open reports/final-report.qmd and render it
  (Command Palette > "Quarto: Render Document").
KT product: open dashboard/index.qmd and render it the same way.
Limitations: cross-sectional data; no causal claims.
Sharing: private repository; course staff have access.

The difference is not length. The strong README answers the reviewer’s questions before they are asked: what the project is, who it is for, where the data comes from, what was found, and how to rerun it.

Path Hygiene

Use relative paths. Avoid:

C:\Users\...
E:\GitHub\...
/Users/name/...

Prefer paths that work from the repository root, such as:

data/clean/analysis.csv
reports/final-report.qmd
dashboard/index.qmd

Dependency Notes

If the project uses R packages beyond the course defaults, document them. If the project uses Python as an optional extension, document how it is launched and which packages are needed.

Keep the dependency note short. The goal is enough information for a reviewer to rerun the work.

Output Hygiene

Generated outputs should be traceable to source code. For each important output, ask:

  • Which source file generates it?
  • Which data file does it use?
  • Can it be regenerated in a fresh Codespace?
  • Is it safe to share publicly?

Git Hygiene

Before final submission:

  • commit repairs with meaningful messages;
  • avoid committing credentials, tokens, or local cache files;
  • keep .gitignore aligned with the project;
  • sync the final commit before submitting the repository link.

Quick Repair Pattern

Use this structure in repair-summary.md:

File changed Problem fixed How verified
README.md Missing render command Followed command in fresh Codespace
report.qmd Absolute data path Rendered with relative path
references.bib Missing citation Citation appeared in rendered report