We have released the first version of a template README for social sciences at https://social-science-data-editors.github.io/template_README/.
The template README provided on this website is in a form that follows best practices as defined by a number of data editors at social science journals.
Joint work with the Review of Economic Studies (Data Editor Miklos Kóren), Economic Journal (Data Editor Joan Llull) and the Canadian Journal of Economics (Data Editor Marie Connolly and previously Peter Morrow ).
We encourage use at AEA journals immediately, and will start to verify usage in May 2021.
We also got input from editors at JOLE (Journal of Labor Economics), JPE (Journal of Political Economy), Management Science (Ben Greiner), and JASA (Journal of the American Statistical Association) (Chris Paciorek) (see JASA’s version at https://jasa-acs.github.io/repro-guide/pages/acc.html). We hope to get additional input from others.
Want to contribute to make it better? Visit us on Github at social-science-data-editors/template_README and create an issue, or provide a pull request.
Want to add your journal to the list of endorsers? Add yourself to social-science-data-editors/template_README.
Purpose and Content
What is the README for? README in the social sciences serve multiple purposes: guiding a reader through the available material, a route to replicating the results in the research paper, including the description of the origins of data and/or description of programs.
We provide templates/examples for Data and Code Availability Statement:
- where do the data come from (see the [Data Citation Principles[(https://www.force11.org/datacitationprinciples)),
- any access restrictions,
- how the data can be used (licenses).
Prove that you are allowed to distribute, help others get access, provide not just an URL! (we provide examples!)
Of course, it contains a (detailed) set of instructions to run the code. But also requirements:
- do you need a laptop from 2010, or a cloud cluster with 102 nodes?
- Runs in 5 minutes, days, weeks, months?
- What packages/dependencies? (we provide examples!)
- Random seed
We note that a good replication package uses a minimal number of automated scripts, with no manual interventions required unless absolutely unavoidable.
The template README has been battle-tested in our attempts (across all of our journals AEA/Restud/EJ/CJE) to assess (computationally, or just by reading) the READMEs of more than 500 articles. If we suggest you provide the information, it’s because it is useful.
Originally posted on Twitter at https://twitter.com/AeaData/status/1336346795878850561.