cleaning up introduction and removing content that goes off track #57
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Signed-off-by: vsoch <vsochat@stanford.edu>
Don't want to imply that donoho talked about containerization
nuest
approved these changes
Apr 15, 2020
There was a problem hiding this comment.
Thanks @vsoch - good job. I'll do another run through and try to remove some repeated content and close the remaining issues today. Besides the open issues, the only thing missing now is a better example Dockerfile for within the article.
| @@ -1,5 +1,5 @@ | |||
| --- | |||
| title: "Ten Simple Rules for Writing Dockerfiles for Reproducible Research" | |||
| title: "Ten Simple Rules for Writing Dockerfiles for Reproducible Data Science" | |||
| By providing this recipe, authors of scientific articles greatly improve their work's level of documentation, transparency, and reusability. | ||
| Such practice is one important part of common practices for scientific computing [@wilson_best_2014; @wilson_good_2017], with the result that it is much more likely both the author and others are able to reproduce and extend an analysis workflow. | ||
| The containers built from these recipes are portable encapsulated snapshots of a specific computing environment. | ||
| Such containers have been demonstrated for capturing scientific notebooks [@rule_ten_2019] and reproducible workflows [@sandve_ten_2013]. | ||
| Research compendia also allow for proper citation of the used computing environment, which is not possible within containers alone. | ||
| Best practices are still a work in progress [cf. @katz_software_2018], but you should try your best to give credit to creators of software you rely on by following recommendations of projects such as CodeMeta ([https://codemeta.github.io/](https://codemeta.github.io/)) and the Citation File Format ([https://citation-file-format.github.io/](https://citation-file-format.github.io/)). |
There was a problem hiding this comment.
Killed one of my darlings here... good job :-).
ten-simple-rules-dockerfiles.Rmd
Outdated
| @@ -369,7 +337,7 @@ You can view all labels with [`docker inspect`](https://docs.docker.com/engine/r | |||
| Labels serve as structured metadata that can be leveraged by services, e.g., https://microbadger.com/labels. | |||
| For example, software versions, license, and maintainer contact information are commonly seen and very useful if a `Dockerfile` is discovered out of context. | |||
| While you can add arbitrarily complex information with labels, for research compendia the user-facing documentation is much more important. | |||
| If you want to earn extra points, and you never know what future algorithms will be able to make sense of, include global identifiers such as [ORCID identifiers](https://orcid.org/) for people, a DOI of the research compendium, e.g., [reserved on Zenodo](https://help.zenodo.org/) before publishing the research compendium, or your funding agency's grant number. | |||
| Important metadata that might be more utilized with future tools includes global identifiers such as [ORCID identifiers](https://orcid.org/), DOIs of the research compendium, e.g., [reserved on Zenodo](https://help.zenodo.org/), or a funding agency's grant number. | |||
There was a problem hiding this comment.
I've re-added the research compendium link here, but am fine with not using the term throughout the article.
| Depositing the image next to other project files, i.e., data, code, and the used `Dockerfile`, in a public repository makes them likely to be preserved, but is is highly unlikely that over time you will be able to recreate it precisely from the accompanying `Dockerfile`. | ||
| Publishing the image and the contained metadata therein (e.g., the Docker version used) may even allow future science historians to emulate the Docker runtime environment. | ||
| Applying proper preservation strategies (cf. [@emsley_framework_2018]) can be highly complex, but simply running an image "as-is", i.e. with the default command and entrypoint (see \ruleref{rule:interactive}), and observing the output is quite likely to work for many years into the future. |
There was a problem hiding this comment.
Another one of my darlings 💀 !! I agree though that container preservation as a topic is not mature enough yet to expose the target audience of this article.
|
Woohoo! Thank you @nuest ! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This pull request is a first shot at cleaning up the manuscript, namely:
I can add comment for any specific choice for reviewers that are interested.
Signed-off-by: vsoch vsochat@stanford.edu