Skip to content

CONTRIB.md

Latest commit

 

History

History
159 lines (111 loc) · 13.1 KB

CONTRIB.md

File metadata and controls

159 lines (111 loc) · 13.1 KB

Contributors Guide

Interested in writing a story with the Maroon Data Team? Follow the steps below.

  1. If you are new, please complete all the getting started steps.
  2. Claim a story on the pitch document (see Slack channel for pitch list) or pitch a new story. To pitch a new story, fill out Data Team Story Outline (TK) and send to a Data Editor for review.
  3. Research, write, and create necessary visuals for your story. Feel free to create draft visuals using any program or language that you would like. Published visuals will need to be created by following the build process. Any visuals that do not follow the build process must be approved by a data editor. Visuals must follow the Maroon's Data Style Guide.

Getting Started

Setup

  1. Make a Github account and learn about version control (git).

  2. Clone the data-visualization repo locally.

    • Learn more about cloning here

  3. Download a code editor

    • If you do not have a strong opinion about which code editor to use, download Visual Studio Code (often just called VS Code). If you do have a strong opinion, feel free to use your preferred choice.
      • learn more about code editors generally here
      • learn more about VS Code here

  4. Download node which will allow you to run Javascript, the programming language we use to write our visualizations in:

    • node.js v20.9.0
      • For Mac or Linux:
        1. Install Node Version Manager with curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash.
        2. Install the correct version of Node nvm install 20.9.0. If you are getting error of nvm not recognized then run source ~/.nvm/nvm.sh and then run above again.
        3. Set this version as the default by running nvm alias default 20.9.0 and nvm use 20.9.0
        4. Confirm the correct version is installed by running node -v. This should return v20.9.0
        5. After you have cloned the repo and downloaded Node, go to the base folder of the data-visualizations repository and run the command npm ci to install all package dependencies. You will only need to do this once.
      • For Windows:
        • Install and run nvm-setup.exe from the NVM for Windows release site.
        • Search for git bash in your applications and open it. If you don't have it, install it from the Git for Windows release site.
        • In this terminal, run the command nvm install 20.9.0
        • Set this version as the default by running nvm alias default 20.9.0 and nvm use 20.9.0
        • Confirm the correct version is installed by running node -v. This should return v20.9.0
        • After you have cloned the repo and downloaded Node, navigate to the base folder of the data-visualizations repository and run the command npm ci to install all package dependencies. You will only need to do this once.

Tools and Skills to Review

Programming is a skill that you learn by doing. There is no expectation that someone fully understands a programming language or package before they can start creating things. Much of the process is about learning as you go and building a muscle of problem solving and debugging as you go.

With that being said, use the resources below as a starting place and reference source. Aim to learn just enough to jump into a project and learn the rest as you go.

  • We primarily use HighCharts, a JavaScript library, to build visualizations. Each HighChart graphic is embedded on a simple HTML page that is linked in its parent story.
    • The best place to start is to find a previously created visual from the Maroon Team by opening https://chicagomaroon.github.io/data-visualizations/example-graphs from your local repository. This will have example charts and links to the accompanying code to review. When creating a data visualization, finding a chart similar to what you’re trying to develop and working off the existing JavaScript code linked.
    • If there is not an example similar to what you want to create, review the Demos tab on the Highcharts website and review the code. You can find the code for that specific visual under the View Code or Copy JS code tabs under the visualization.
    • Continue to Build Process for a Visualization
  • Additional resources

Build Process for a Visualization

  1. Go to the base folder of the data-visualizations repository and ensure your local repo is up to date with the remote repo by running git checkout main and git pull

  2. Create a branch for your story by running git checkout -b '[kebab-case-story-name]'. Replace the values in brackets with the relevant names. Read more about kebab-case here.

  3. In the terminal run npm run create-visual --year=[year] --story=[kebab-case-story-name] This will create a folder with all the necessary files to create your visual.

    • If it is the year 2024 and your story is called Example Visual then run the command npm run create-visual --year=2023 --story=example-visual using the year 2024 and your story's name example-visual in kebab-case.
    • For the error The syntax of the command is incorrect, use ChatGPT to edit the command for your terminal. For example, Git Bash requires line breaks. You may also have to manually set environment variables with npm_config_year= and npm_config_story=.
    • In your ./[year]/[story-name]/ folder, there will be a file called main.js. This is where you’ll write the JavaScript logic for your visual.

  4. Start creating your visual that will be housed in the ./[year]/[story-name]/ folder.

  5. Update the meta_data.json in your story's folder, which will look something like this:

    {
    "title": "Example Visual",
    "description": "Describe your visual"
}
    • Make sure the title you write in the meta_data.json file is the same as the title you give your visual in main.js and in index.html's <title> tag.

  6. Run npm run format and make the changes that the output recommends. Also ensure the title, subtitle, and captions follow the requirements in the Contribution Standards section. Ensure the chart and annotations still look correct at a width of ~700px. This is the width of the charts when online.

  7. Go to the base folder of the data-visualizations repository and run the command npm run process-visual --year=[year] --story=[kebab-case-story-name]

    • Example: npm run process-visual --year=2023 --story=example-visual

  8. Create a Pull Request to have your visual reviewed by committing and pushing your changes.

    • In your pull request, include a screenshot of the visual. Ensure the visual is ~700px.
    • You can run git status to see which files in red have not been added. Then run git add [file-name] for each file to add them. Next run git commit -m '[commit message]' to commit your changes. Then run git push to push your changes. If this is your first commit, github may ask you to run a different command, which you should. Ex git push --set-upstream origin [branch-name]

The Chicago Maroon’s Data Contribution and Style Guide

Contribution Standards

Pull Request Titles

They should be written in the present imperative tense. Examples of that tense are: "Fix issue in the dispatcher where…", "Improve our handling of…", etc."

Pull Request Information

All pull requests should contain a still of the image and be linted, minified, contain no more imports than needed, and approved by at least one of the Lead Developers.

Style Standards

Examples for external style guides for inspiration.

Font

The font is set via the main.css file. The default font, and the one used on the rest of The Chicago Maroon, is Georgia, serif font.

Titles, Subtitles, and Captions

Plot title: A few words describing what the plot is about (can be a phrase or a question, not a full statement) Plot subtitle (optional): A short sentence summarizing the main takeaway from the data; should end with a period Plot caption (optional): Any asterisk-style note that adds important clarifying context to part of the plot (ex: if data for one year is incomplete, put an asterisk on that year and make an asterisk-prefixed note in the caption) HTML caption (Adding in SNO): One or more longer sentences explaining findings and tying the plot to the story and a link to the data source (on a new line)

In addition itles and subtitles should meet the following constraints:

  • They should ideally not take up more than one line each.
  • They should be centered, not left or right-justified.
  • Links should be added using anchor tags.

Colors

Color palettes are based off the UChicago style guide.

UChicago primary colors.

UChicago secondary colors.

Additional Resources

Tools

  • Google Sheets: Often the best tool to work with csv's or any tabular data is Google Sheets. You can review, filter, and pivot the data as well as make draft visuals
  • R and Python: For more data-intensive projects, you may want to consider using R or Python. See examples in the data-analysis folder.
  • For mapping, we have used Leaflet, an open-source JavaScript library, for mobile-friendly interactive maps. You can also use GeoJSON.io to draw on a map and get the coordinates as a .geojson file.
  • For more customizable, interactive visualizations, D3.js has become a popular package. There is a steep learning curve for this tool but gives you total control over your visuals. Austin developed a D3 training based on James Turk's Data Visualization course. Recommended prerequisites include HTML/CSS.
  • You may be interested in creating more accessible visuals for a broad audience. One option is to start with this short introduction to accessibility on the web.

Training

See the [resources][resources/] folder for additional training materials.

Inspiration

Organizations