datamade / data-making-guidelines

:blue_book: Making Data, the DataMade Way

Making Data, the DataMade Way

This is DataMade's guide to extracting, transforming and loading (ETL) data using Make, a common command line utility.

This guide is part of a body of technical and process documentation maintained by DataMade. Head over to datamade/how-to for other guides on topics ranging from AWS to work practices!

What is ETL?

ETL refers to the general process of:

1. taking raw source data ("Extract")
2. doing some stuff to get the data in shape, possibly involving intermediate derived files ("Transform")
3. producing final output in a more usable form (for "Loading" into something that consumes the data - be it an app, a system, a visualization, etc.)

Having a standard ETL workflow helps us make sure that our work is clean, consistent, and easy to reproduce. By following these guidelines you'll be able to keep your work up to date and share it with the world in a standard format - all with as few headaches as possible.

Basic Principles

These five principles inform all of our data work:

1. Never destroy data - treat source data as immutable, and show your work when you modify it
2. Be able to deterministically produce the final data with one command
3. Write as little custom code as possible
4. Use standard tools whenever possible
5. Keep source data under version control

Unsure how to follow these principles? Read on!

The Guide

1. Make & Makefile Overview
   • Why Use Make/Makefiles?
   • Makefile 101
   • Makefile 201 - Some Fancy Things Built Into Make
2. ETL Styleguide
   • Makefile Best Practices
   • Variables
   • Processors
   • Standard Toolkit
   • ETL Workflow Directory Structure

Code examples

• Some Annotated ETL Code Examples with Make
• Recipes for Common Makefile Operations
• Chicago Lead - data work with a clear README and Makefile
• EITC Works - adding data attributes to Illinois House and Senate district shapefiles and outputting at GeoJSON

Further reading

• Makefile Style Guide by Clark Grubb
• Why Use Make by Mike Bostock