updated contributing guide + PR template

.github/PULL_REQUEST_TEMPLATE

@@ -1,6 +1,22 @@
-- [ ] I followed the [CONTRIBUTING guidelines](../blob/main/CONTRIBUTING.md).
+# Changes in this PR
+<!--
+Give a brief description of the PR, mainly: why & what.
+Link relevant issues as well.
+-->
 
-Below, describe what this Pull Request adds:
 
 
-
+# Checklist
+<!--
+Use the checklist below to make sure you followed the [CONTRIBUTING guidelines](https://guide.esciencecenter.nl/#/CONTRIBUTING).
+Feel free to remove what is not applicable.
+-->
+
+## SIGNIFICANT changes / additions, e.g. new chapters
+- [ ] I checked whether the contribution fits in [The Turing Way](https://github.com/the-turing-way/the-turing-way) before considering contributing to this Guide.
+- [ ] I discussed my contribution in an issue and took into account feedback.
+
+## ALL contributions
+- [ ] I previewed my changes locally using e.g. `python3 -m http.server 4000` and confirmed they work correctly.
+- [ ] I checked for broken links, e.g. using the link checker GitHub Action workflow, or locally by using `docker run --init -it -v `pwd`:/docs lycheeverse/lychee /docs --config=docs/lychee.toml`, at least for the files I changed.
+- [ ] My name was added to the `CITATION.cff` file.

CONTRIBUTING.md

@@ -1,21 +1,86 @@
-# Contributing
+# Contributing to the Guide
+- [Who? You!](#who_you)
+- [Audience](#audience)
+- [Scope](#scope)
+- [How?](#how)
+- [Technical details (docsify)](#technical-details)
+- [Zen of the Guide](#zen-of-the-guide)
 
-This guide is primarily written by the eScience Research Engineers at the Netherlands eScience Center. The intended audience is anyone interested in eScience and research software development in general or how this is done at the eScience Center specifically.
 
-## Scope
+# Who? You!
 
-Please check if your contribution fits in
-[The Turing Way](https://github.com/the-turing-way/the-turing-way)
-before considering contributing to this guide.
-If it does not fit, please open an [issue](https://github.com/NLeSC/guide/issues)
-to discuss your planned contribution before starting to work on it, to avoid
-disappointment later.
+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!
 
-To make sure the information in this guide stays relevant and  up to date it is intentionally low on technical details. The guide contains information on the process we use to do projects and develop software.
+## Page maintainers
+
+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*.
+
+## Editorial board
+
+The editors make sure content is in line with [the scope](#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](https://github.com/bouweandela) (research software engineer)
+- Carlos Martínez Ortiz [@c-martinez](https://github.com/c-martinez) (community manager)
+- Patrick Bos [@egpbos](https://github.com/egpbos) (technology lead)
+
+
+
+# Audience
+
+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.
+
+
+# Scope
+
+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.
 
-## Workflow for making contributions
+80% of this goal will be met by [the Turing Way](https://the-turing-way.netlify.app/).
+For everything else: we have the Guide.
 
-Contributions by anyone are most welcome.
+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:
+
+1. Project related practices (planning, communication, stake holders, management, etc.). These we gather on our intranet pages.
+2. Project output is gathered on the [Research Software Directory](https://research-software-directory.org/organisations/netherlands-escience-center?tab=software&order=is_featured).
+3. Generic research software engineering advice that can be added to [The Turing Way](https://github.com/the-turing-way/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.
+
+
+## For significant changes / additions, especially new chapters
+Please check if your contribution fits in [The Turing Way](https://github.com/the-turing-way/the-turing-way) before considering contributing to this guide.
+Feel free to ask the [editors](#editorial-board) if you are unsure or open an [issue](https://github.com/NLeSC/guide/issues) to discuss it.
+If it does not fit, please open an [issue](https://github.com/NLeSC/guide/issues) to discuss your planned contribution before starting to work on it, to avoid disappointment later.
+
+
+# How?
 
 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.
 
@@ -27,15 +92,15 @@ git checkout newbranch
 
 Add your new awesome feature, fix bugs, make other changes.
 
-To view changes locally, host the repo with a static file web server.
+To preview changes locally, host the repo with a static file web server:
 
 ```shell
 python3 -m http.server 4000
 ```
 
-To view the documentation in a web browser (default address: http://localhost:4000):
+to view the documentation in a web browser (default address: http://localhost:4000).
 
-To check if there are any broken links using [lychee](https://github.com/lycheeverse/lychee) in a Docker container:
+To check if there are any broken links use [lychee](https://github.com/lycheeverse/lychee) in a Docker container:
 
 ```shell
 docker run --init -it -v `pwd`:/docs lycheeverse/lychee /docs --config=docs/lychee.toml
@@ -45,16 +110,12 @@ If everything works as it should, ``git add``, ``commit`` and ``push`` like norm
 
 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.
 
-## Page maintainers
-
-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*.
-
 ## Create a PDF file
 
-We host a PDF version of the guide on [Zenodo](https://doi.org/10.5281/zenodo.4020565).
+We host a PDF version of the guide on [Zenodo](https://doi.org/10.5281/zenodo.4020564).
 To update it a [new release](https://github.com/NLeSC/guide/releases) needs to be made of the guide. This will trigger a GitHub action to create a new Zenodo version with the PDF file.
 
+
 # Technical details
 
 The basics of how the Guide is implemented.
@@ -73,3 +134,27 @@ Plugins that we use:
 - [Prism](https://docsify.js.org/#/language-highlight) is used for language highlighting.
 
 If you want to change anything in this part, please discuss in an issue.
+
+
+# Zen of the Guide
+
+0. Help your colleagues.
+1. Citing is better than copying.
+2. Copying is better than rewriting from scratch.
+3. ... but leaving out is often even better.
+4. Don't state the obvious.
+5. Don't assume that something is obvious.
+6. Snippets are friends.
+7. Remove outdated content.
+8. Better yet, update outdated content.
+9. Your practices are just _your_ practices. Best practices are shared practices. $N>1$.
+10. Our best practices are just _our_ best practices. We don't have to agree with everyone.
+11. Best practices are timeless (at least for a year or so).
+12. Best practices are never set in stone. They are set in the Guide.
+13. Best practices are not always practices.
+14. ~~Best practices are not always best practices.~~
+15. Kill your darlings.
+16. Consider The Turing Way first.
+17. Sharing is better than guiding.
+18. Guiding is better than turning a blind eye.
+19. This Guide shall be under your pillow.