Skip to content

Latest commit

 

History

History
38 lines (24 loc) · 2.86 KB

Project_Completion_Guidelines.md

File metadata and controls

38 lines (24 loc) · 2.86 KB
Raw

Project completion guidelines

In the Zipkin Lab, we strive to make our work transparent and reproducible. The following is a checklist with all information that should be included upon completion of a project (i.e., publication of a paper). This document is intended to serve as a guide, covering the necessary components of most projects (but may vary slightly from project to project). It is preferable, and probably easier, to keep these requirements in mind throughout project development and upload documents as they become available (or to code directly through Git), but all elements should be present at project wrap-up.

General project requirements and documentation

All project components must be hosted in a public repository on Github, which should be linked to the lab's Github site. The project repo should be clearly named and ideally contain the code and data used during project development. At a minimum, the repo must contain all the final data and code files, as well as a README file (in a separate, clearly marked folder if there are a number of files in the project repo). The README file should provide the following information:

  • Project abstract or description with a link to the published paper (if applicable).
  • Description of final file contents including appropriate metadata.
  • File navigation within repo if there are a large number of files or if there are a number of extraneous files to the final product.
  • A license so people know how they can use your work, especially if there are any restrictions. Our work has little to no commercial value :) so this should not be a major issue in most cases.

Data

Data used in support of the project must be:

  • Saved in an appropriate, non-proprietary format with accompanying metadata.
  • In a public archive (e.g., Zenodo), or, if data are proprietary, a version of the data used in the project must be saved in the lab's private repository.
  • Linked and briefly described in the project README. The README file should contain all metadata including descriptions of data fields even if the data are not made publically available.

Code

The final code files used or developed in support of the project must all be:

  • Well commented and complete.
  • On Github, in the public project repository.
  • Described in the README - what does each file do, what language was used, etc.

Website

The website provides a front-end for people navigating our projects by research area and may be viewed by less technical users. Help them understand the components of your work by:

  • Linking project repo from website.
  • Giving a plain language project description. In most cases, this will be the paper's abstract.
  • Including contact information for authors, and if data are proprietary, for data creators/owners.
  • Making it pretty by including a snazzy graphic as a thumbnail.