This guide is primarily written by the Research Software Engineers at the Netherlands eScience Center. Contributions by anyone (also outside the Center) are most welcome!
While everybody is encouraged to contribute where they can, we appoint maintainers for specific pages to regularly keep things up to date and think along with contributors. To see who is responsible for which part of the guide see the maintainer listed at the top of a page. If you are interested in becoming a chapter owner for a page that is listed as unmaintained, please open a pull request to add your name instead of unmaintained.
The editors make sure content is in line with the scope, that it is maintainable and that it is maintained. In practice they will:
- track, lead towards satisfactory conclusion of and when necessary (in case of disagreement) decide on issues, discussions and pull requests,
- flag content that needs to be updated or removed,
- ask for input from page maintainers or other contributors,
- periodically organize sprints to work on content together with everyone interested in contributing; usually in the form of a "Book Dash" together with The Turing Way contributors,
and do any other regular editing tasks.
Currently the team consists of:
- Bouwe Andela @bouweandela (research software engineer)
- Carlos Martínez Ortiz @c-martinez (community manager)
- Patrick Bos @egpbos (technology lead)
Our eScience Center RSEs are the prototypical audience members, in particular those starting out in some unfamiliar area of technology. Some characteristics include:
- They are interested in intermediate to advanced level best practices. If there are already ten easily found blog posts about it, it doesn't have to be in the Guide.
- They are a programmer or researcher that is already familiar with some other programming language or software-related technology.
- They may be generally interested (in particular topics of eScience practice and research software development in general or how this is done at the eScience Center specifically), but their main aim is towards practical application, not to create a literature study of the current landscape of (research) software.
To make sure the information in this guide stays relevant and up to date it is intentionally low on technical details. The guide contains and links to best practices we use to code and develop research software in our projects.
The main goal: having information available about research software engineering best practices for our colleagues, collaborators and other interested people. It can be information that you can give a colleague starting in some area, for instance, a new language or a new technology.
80% of this goal will be met by the Turing Way. For everything else: we have the Guide.
We focus on eScience Center-specific best practices.
These can be generic and complete or specific and highly curated.
It depends!
For instance, eScience specific content (e.g. we prefer git over svn) should be in the Guide, while content of interest to a general audience (e.g. it is good practice to use a version control system) should go in The Turing Way.
When in doubt, discuss your doubts in an issue.
A few things are excluded:
- Project related practices (planning, communication, stake holders, management, etc.). These we gather on our intranet pages.
- Project output is gathered on the Research Software Directory.
- Generic research software engineering advice that can be added to The Turing Way.
In practice, this means the Guide (for now) will mostly consist of language guides and technology guides.
It can also sometimes function as a staging/draft area for eventually moving content to the Turing Way. However, we will urge you to contribute to the Turing Way directly.
Please check if your contribution fits in The Turing Way before considering contributing to this guide. Feel free to ask the editors if you are unsure or open an issue to discuss it. If it does not fit, please open an issue to discuss your planned contribution before starting to work on it, to avoid disappointment later.
A well written piece of advice should contain the following information:
- What, e.g. version control
- Why, e.g. why version control is a good idea
- Short how / tl;dr: Recommend one solution for readers who don't want to spend time reading about all possible options, e.g. at NLeSC we use git with GitHub because... This is where NLeSC specific info should go if it makes sense to do so.
- Long how: also explain other options for implementing advice, e.g. here's a list of some more version control programs and/or services which we can recommend.
Please use branches and pull requests to contribute content. If you are not part of the Netherlands eScience Center organization but would still like to contribute please do by submitting a pull request from a fork.
git clone https://github.com/NLeSC/guide.git
git branch newbranch
git checkout newbranchAdd your new awesome feature, fix bugs, make other changes.
To preview changes locally, host the repo with a static file web server:
python3 -m http.server 4000to view the documentation in a web browser (default address: http://localhost:4000).
To check if there are any broken links use lychee in a Docker container:
docker run --init -it -v `pwd`:/docs lycheeverse/lychee /docs --config=docs/lychee.tomlIf everything works as it should, git add, commit and push like normal.
If you have made a significant contribution to the guide, please make sure to add yourself to the CITATION.cff file so your name can be included in the list of authors of the guide.
We host a PDF version of the guide on Zenodo. To update it a new release needs to be made of the guide. This will trigger a GitHub action to create a new Zenodo version with the PDF file.
The basics of how the Guide is implemented.
The Guide is rendered by docsify and hosted on GitHub Pages. Deployment is "automatic" from the main branch, because docsify requires no build step into static HTML pages, but rather generates HTML dynamically from the MarkDown files in the Guide repository. The only configuration that was necessary for this automatic deployment is:
- The index.html file in the root directory that loads docsify.
- The empty .nojekyll file, which tells GitHub that we're not dealing with Jekyll here (the GitHub Pages default).
- Telling GitHub in the Settings -> Pages menu to load the Pages content from the root directory.
- The _sidebar.md file for the table of contents.
Plugins that we use:
- The docsify full text search plugin
- The docsify Google Analytics plugin
- Prism is used for language highlighting.
If you want to change anything in this part, please discuss in an issue.
- Help your colleagues.
- Citing is better than copying.
- Copying is better than rewriting from scratch.
- ... but leaving out is often even better.
- Don't state the obvious.
- Don't assume that something is obvious.
- Snippets are friends.
- Remove outdated content.
- Better yet, update outdated content.
- Your practices are just your practices. Best practices are shared practices.
$N>1$ . - Our best practices are just our best practices. We don't have to agree with everyone.
- Best practices are timeless (at least for a year or so).
- Best practices are never set in stone. They are set in the Guide.
- Best practices are not always practices.
Best practices are not always best practices.- Kill your darlings.
- Consider The Turing Way first.
- Sharing is better than guiding.
- Guiding is better than turning a blind eye.
- This Guide shall be under your pillow.