Skip to content

Commit 356db51

Browse files
mariaob1201mariaob1201
authored
Revise README for 2024 survey details and usage
Updated README to include new survey results and repository usage instructions.
1 parent 224d98b commit 356db51

File tree

1 file changed

+144
-46
lines changed

1 file changed

+144
-46
lines changed

‎README.md‎

Lines changed: 144 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,196 @@
11
# 2024 UW–Madison Open Source Program Office Survey
22

33
[![Deploy to GitHub Pages](https://github.com/UW-Madison-DSI/open_source_survey_results_myst/actions/workflows/publish.yml/badge.svg)](https://github.com/UW-Madison-DSI/open_source_survey_results_myst/actions/workflows/publish.yml)
4+
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17379408.svg)](https://doi.org/10.5281/zenodo.17379408)
5+
6+
In Spring 2024, the [Open Source Program Office at UW–Madison](https://ospo.wisc.edu/) conducted a survey to:
7+
8+
- Assess the use of open source tools across the university community
9+
- Identify open source projects currently under development
10+
- Gather feedback on strengthening the open source ecosystem at UW–Madison
411

5-
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17525692.svg)](https://doi.org/10.5281/zenodo.17525692)
12+
This repository hosts a [MyST site](https://mystmd.org) that summarizes and presents results from the survey.
13+
14+
📍 **Live site:** [Survey Results on GitHub Pages](https://uw-madison-dsi.github.io/open_source_survey_results_myst/)
15+
📍 **Companion site (Quarto, for R users):** [Quarto site](https://uw-madison-dsi.github.io/open_source_survey_results/)
616

717
---
818

9-
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17379408.svg)](https://doi.org/10.5281/zenodo.17379408)
19+
## 🎯 Two Ways to Use This Repository
1020

11-
In Spring 2024, the [Open Source Program Office at UW–Madison](https://ospo.wisc.edu/) conducted a survey to:
21+
### 1️⃣ View UW-Madison's Survey Results (Current Branch: `main`)
1222

13-
- Assess the use of open source tools across the university community
14-
- Identify open source projects currently under development
15-
- Gather feedback on strengthening the open source ecosystem at UW–Madison
23+
Explore our findings on open source usage, campus culture, and community needs at UW-Madison.
1624

17-
This repository hosts a [MyST site](https://mystmd.org) that summarizes and presents results from the survey.
25+
### 2️⃣ Create Your Own Survey Site (Branch: `cookiecutter-template`)
1826

19-
📍 **Live MyST site:** [Survey Results (MyST)](https://uw-madison-dsi.github.io/open_source_survey_results_myst/)
20-
📍 **R-based Quarto site:** [Survey Results (Quarto)](https://uw-madison-dsi.github.io/open_source_survey_results/)
27+
**Conducting a similar survey at your institution?** Use our Cookiecutter template to generate a fully customized version!
28+
```bash
29+
# Install cookiecutter
30+
pip install cookiecutter
31+
32+
# Generate your own survey site
33+
cookiecutter gh:UW-Madison-DSI/open_source_survey_results_myst --checkout cookiecutter-template
34+
```
35+
36+
**The template will prompt you for:**
37+
- Institution name and branding
38+
- Primary color (hex code)
39+
- Contact information
40+
- Survey year
41+
- GitHub organization
42+
43+
**What you get:**
44+
- ✅ Customized MyST site with your institution's branding
45+
- ✅ All analysis code and structure from our survey
46+
- ✅ GitHub Actions workflow for automatic deployment
47+
- ✅ Interactive Plotly visualizations
48+
- ✅ Responsive design with custom footer
49+
50+
[**→ Learn more about the template**](https://github.com/UW-Madison-DSI/open_source_survey_results_myst/tree/cookiecutter-template)
2151

2252
---
2353

24-
## 📌 Table of Contents
54+
## Repository Overview
55+
56+
- **`survey_results_docs/docs/`** – Source files for the MyST site
57+
- **`setup.py`** – University branding and plot styling
58+
- **`_config.yml`** – Site configuration
59+
- **Page files (e.g., `usage.md`, `campus.md`)** – Survey-specific analyses and visualizations
60+
- **`data/`** – Anonymized survey data
61+
- **`_static/`** – Custom CSS, logos, and assets
2562

26-
- [Two Ways to Use This Repository](#-two-ways-to-use-this-repository)
27-
- [Repository Overview](#repository-overview)
28-
- [Technical Stack](#technical-stack)
29-
- [Build Locally](#build-locally)
30-
- [Project Structure](#-project-structure)
31-
- [Citation](#citation)
32-
- [Survey Resources](#-survey-resources)
33-
- [Contributing](#-contributing)
34-
- [Contact](#-contact)
35-
- [Acknowledgments](#-acknowledgments)
36-
- [License](#-license)
63+
🔧 **Customization:**
64+
- Theming (colors, fonts, layout) is managed in `setup.py` and `_config.yml`
65+
- Figures and highlights for open source tools are defined within the individual page files
3766

3867
---
3968

40-
## 🎯 Two Ways to Use This Repository
69+
## Technical Stack
4170

42-
### 1️⃣ View UW–Madison's Survey Results (Branch: `main`)
71+
This project is built with:
4372

44-
Explore our findings on open source usage, campus culture, and community needs at UW–Madison.
73+
- [MyST Markdown](https://mystmd.org/) and [Jupyter Book](https://jupyterbook.org/) for site generation
74+
- [Python](https://www.python.org/) for data wrangling and analysis
75+
- [Plotly](https://plotly.com/python/) for interactive visualizations
76+
- [GitHub Actions](https://docs.github.com/actions) for automated deployment to GitHub Pages
4577

46-
To build and preview the site on your machine:
78+
---
79+
80+
## Build Locally
4781

48-
```commandline
82+
To build and preview the site on your machine:
83+
```bash
4984
# Navigate to docs folder
5085
cd survey_results_docs/docs
5186

5287
# Install dependencies
53-
pip install -U jupyter-book
88+
pip install 'jupyter-book<2.0' pandas plotly matplotlib
5489

5590
# Build the site
5691
jupyter-book clean .
5792
jupyter-book build .
5893

5994
# Open in browser
6095
open _build/html/index.html
96+
6197
# Or run a local server
6298
python -m http.server -d _build/html
6399
```
64100

65-
### 2️⃣ Create Your Own Survey Site (Branch: `cookiecutter-template`)
101+
---
66102

67-
**Conducting a similar survey at your institution?** Use our Cookiecutter template to generate a fully customized version:
103+
## 📁 Project Structure
104+
```
105+
open_source_survey_results_myst/
106+
├── .github/workflows/
107+
│ └── publish.yml # GitHub Actions deployment
108+
├── survey_results_docs/docs/
109+
│ ├── _config.yml # Jupyter Book configuration
110+
│ ├── _toc.yml # Table of contents
111+
│ ├── _static/ # CSS, images, logos
112+
│ ├── data/ # Survey data (anonymized CSV)
113+
│ ├── setup.py # Python utilities and theming
114+
│ ├── index.md # Home page
115+
│ ├── sample.md # Demographics analysis
116+
│ ├── usage.md # Tool usage patterns
117+
│ ├── sentiments.md # Perceptions and value
118+
│ ├── campus.md # Campus culture
119+
│ └── reproduction.md # Reproduction guide
120+
└── README.md
121+
```
68122

69-
```bash
70-
pip install cookiecutter
123+
---
71124

72-
cookiecutter gh:UW-Madison-DSI/open_source_survey_results_myst --checkout cookiecutter-template
125+
## Citation
126+
127+
If you use this work or reproduce the survey at your institution, please cite:
128+
129+
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.17379408.svg)](https://doi.org/10.5281/zenodo.17379408)
130+
```bibtex
131+
@misc{uw_madison_ospo_2024,
132+
title={UW-Madison Open Source Program Office Survey Results},
133+
author={UW-Madison Data Science Institute},
134+
year={2024},
135+
doi={10.5281/zenodo.17379408},
136+
url={https://uw-madison-dsi.github.io/open_source_survey_results_myst/}
137+
}
73138
```
74139

140+
---
75141

76-
## Repository Overview
142+
## 📊 Survey Resources
77143

78-
- **`docs/`** – Source files for the MyST site
79-
- **`setup.py`** – University branding and plot styling
80-
- **Page files (e.g., `usage.qmd`)** – Survey-specific analyses, figures, and customizations
144+
- **Survey instrument (Qualtrics .qsf):** [Download](https://github.com/UW-Madison-DSI/open_source_survey_results/blob/main/Open_Source_Program_Office_Survey.qsf)
145+
- **Anonymized data:** Available in `survey_results_docs/docs/data/`
146+
- **Reproduction guide:** See [reproduction.md](https://uw-madison-dsi.github.io/open_source_survey_results_myst/reproduction.html)
81147

82-
🔧 **Customization:**
83-
- Theming (colors, fonts, layout) is managed in `setup.py`.
84-
- Figures and highlights for open source tools are defined within the individual page files.
148+
This project was inspired by the [NYU DS3 Needs Assessment Survey](https://github.com/ds3-nyu/Needs-Assessment-Survey).
85149

86150
---
87151

88-
## Technical Stack
152+
## 🤝 Contributing
153+
154+
Contributions are welcome! Whether you're:
155+
- Fixing bugs or typos
156+
- Improving documentation
157+
- Enhancing visualizations
158+
- Sharing feedback on the survey methodology
159+
160+
Please open an issue or submit a pull request.
161+
162+
---
163+
164+
## 📧 Contact
165+
166+
**Data Science Institute**
167+
- Email: maria.oros@wisc.edu
168+
**UW-Madison Open Source Program Office**
169+
- Email: ospo@datascience.wisc.edu
170+
- Website: https://ospo.wisc.edu
171+
- Twitter: [@datascience_uw](https://x.com/datascience_uw)
172+
- Join our community: [OSPO Google Group](https://groups.google.com/g/ospo-uw)
173+
174+
---
175+
176+
## 🌟 Acknowledgments
177+
178+
This project was made possible by a grant from the [Alfred P. Sloan Foundation](https://sloan.org/).
179+
180+
Special thanks to:
181+
- UW-Madison Data Science Institute
182+
- UW-Madison Libraries
183+
- All survey participants who shared their experiences
184+
- The MyST, Jupyter Book, and Plotly communities
185+
186+
---
187+
188+
## 📜 License
89189

90-
This project is built with:
91-
- [MyST Markdown](https://mystmd.org/) and [Jupyter Book](https://jupyterbook.org/) for site generation
92-
- [Python](https://www.python.org/) for data wrangling and analysis
93-
- [Plotly](https://plotly.com/python/) for interactive visualizations
94-
- [GitHub Actions](https://docs.github.com/actions) for automated deployment to GitHub Pages
190+
This project is open source and available under the [MIT License](LICENSE).
95191

96192
---
97193

98-
Maria Oros, Data Scientist
194+
<div align="center">
195+
<sub>Built with ❤️ by the UW-Madison Open Source Program Office</sub>
196+
</div>

0 commit comments

Comments
 (0)