fix links and mention new page on homepage

nuest · nuest · commit 3aad5d159378 · 2024-11-07T13:31:17.000+01:00
diff --git a/guide/community-workflow-author.md b/guide/community-workflow-author.md
@@ -13,7 +13,7 @@ See also the [CODECHECK community workflow overview](/guide/community-workflow-o
 
 <span style="font-size: 60%; color: grey;">Inspired by Greg Wilson's first rule of <a href="http://teachtogether.tech/" title="Teaching Tech Together">Teaching Tech Together</a>.</span>
 
-### Background
+### 1. Background
 
 The author must provide a _[preproducible](https://doi.org/10.1038/d41586-018-05256-0) workflow_:
 all data and code files necessary to reproduce the results are provided in a way that allows fellow researchers to follow and execute the steps.
@@ -32,7 +32,7 @@ Structured information about the computing environment, such as a _colophon_ or
 Common sense shall be applied to decide about the suitable amount of data and to handle big datasets, sensitive datasets with privacy concerns, and long execution times.
 For example, data may be deposited depending on community practices in remote repositories, synthetic data may be used, subsets or preprocessed data may be included, or protected access to information may be provided (e.g. cloud-based data enclaves).
 
-### Requirements
+### 2. Requirements
 
 The minimal set of files, besides all required data and code, to implement a CODECHECK process are the following ones (`.` is the project root directory, which could be for example, `/home/username/research-project/2020/great-paper`).
 Ideally, the author supplies first versions of these three files, though they might also be jointly created in collaboration with the codechecker.
@@ -43,14 +43,14 @@ In case of the metadata,  parts of the metadata will be provided by the codechec
 1. **`./codecheck.yml` file** with basic metadata and a list of output files created by the workflow, the so called manifest; these files must be created by the workflow and are the basis for validating a successful CODECHECK; see the [latest CODECHECK configuration file specification]({{ 'spec/config/latest' | absolute_url }}) for the required and optional contents and start with the [_minimal example for authors_]({{ 'spec/config/1.0/#tldr-for-authors' | absolute_url }})
 1. **`./LICENSE` file** with information about licenses for all submitted material, e.g. code license for scripts and data licenses for used datasets; see [The Turing Way](https://book.the-turing-way.org/reproducible-research/licensing.html) on licensing for guidance
 
-### Publication
+### 3. Publication of workflow
 
 The required files and the workflow code and data are published in a dedicated self-contained repository in the [codecheckers organisation on GitHub](https://github.com/codecheckers/).
 This happens by [forking](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) the authors repository, if one already exist.
 If the repository is on GitLab(.com), the [cdchck organisation on GitLab](https://gitlab.com/cdchck) can be used.
 After the CODECHECK, authors may transfer the improvements and certificate back to their own repository.
 
-### Extras
+### 4. Extras
 
 Beyond the minimally required files to run a workflow, any additional configuration and information is extremely helpful, of course, and can greatly improve the smoothness of the CODECHECK process.
 Some hints as to what this can entail are given by the codechecker's tasks below - it is worth taking the checker's perspective to improve your submission.
@@ -69,11 +69,11 @@ Feel free to inquire in the [CODECHECK discussion forum](https://github.com/orgs
 
 A great way to learn what a good way to meaningfully package your research for others to inspect, understand, and reproduce is to participate in a [ReproHack](https://reprohack.github.io/reprohack-hq/) and take on the reader/codechecker perspective.
 
-### Submission
+### 5. Submission to CODECHECK
 
-When your workflow is ready to be CODECHECKed, open an issue on the [CODECHECK register](https://github.com/codecheckers/register/issues/new/choose).
+When your workflow is ready to be codechecked, open an issue on the [CODECHECK register](https://github.com/codecheckers/register/issues/new/choose).
 
-### During submission/preprint stage
+### 6. During submission/preprint stage
 
 After the publication of the CODECHECK certificate, add a reference to the certificate in your paper, e.g., in a section describing your workflow or in the acknowledgements:
 
@@ -85,5 +85,6 @@ After the publication of the CODECHECK certificate, add a reference to the certi
 
 See the [CODECHECK register](/register) for a full list of codechecks, including direct links to the certificates.
 Take a look at existing checks for your discipline or community to get an impression on how CODECHECKs work.
+Selected examples are on the [workflow overview page](/guide/community-workflow-overview).
 
 _Is your scientific dispipline missing?_ Time to **[get involved!](/get-involved)**.
diff --git a/guide/community-workflow-codechecker.md b/guide/community-workflow-codechecker.md
@@ -1,7 +1,6 @@
 ---
 layout: page
 title: CODECHECK community workflow for codecheckers
-permalink: guide/community-workflow
 ---
 
 See also the [CODECHECK community workflow overview](/guide/community-workflow-overview) and [discuss your issues](https://github.com/orgs/codecheckers/discussions).
@@ -18,10 +17,10 @@ Now it's your turn.
 1. Create a repository in the CODECHECK GitHub organization, either by forking existing repository or creating new one and uploading materials
 1. Create a new directory in that repository where all new files will go
 1. Create a new document to write the CODECHECK certificate and *start documenting the ongoing codecheck now*
-   The exact form of  a codechecking procedure and form of documentation vary greatly, but there are some tools, such as [an R package](https://github.com/codecheckers/codecheck) to automate some steps, including [an Rmd template](https://github.com/codecheckers/codecheck/blob/master/inst/extdata/templates/codecheck/codecheck.Rmd); all of that is optional, as long as the final report contains the mandatory information
+   The exact form of  a codechecking procedure and form of documentation vary greatly, but there are some tools, such as [an R package](https://github.com/codecheckers/codecheck) to automate some steps, including [an Rmd template](https://github.com/codecheckers/codecheck/blob/master/inst/extdata/templates/codecheck/codecheck.Rmd); all of that is optional, as long as the final certificate contains the mandatory information
 1. Open the manuscript and follow the instructions to reproduce a workflow
 1. During the CODECHECK, contact the authors in case of problems; keep in mind the general [CODECHECK principles](/project/#the-codecheck-principles), especially “the codechecker records but does not fix” – unless it is a very trivial bug like pathnames; the authors can provide updated versions of code and documentation; however, the entire procedure should not be much more time-intensive than a normal peer review of a paper and not involve more than a few code revisions; the codechecker can always stop the process after a reasonable effort and close the issue as not successfully reproduced.
-1. Summarize the process and outcomes in your certificate and upload it as PDF to [Zenodo](https://zenodo.org/) or [OSF](https://osf.io/); add edited files and intemediary as well as output files as you see fit; the certifiate must at least contain the information on who checked what and how; the ambition should be to document for future self and other researchers; have a look at the available reports.
+1. Summarize the process and outcomes in your certificate and upload it as PDF to [Zenodo](https://zenodo.org/) or [OSF](https://osf.io/); add edited files and intemediary as well as output files as you see fit; the certifiate must at least contain the information on who checked what and how; the ambition should be to document for future self and other researchers; have a look at the available certificates.
 1. Adds a pull request to original repository for the CODECHECK badge (optional)
 1. Notify the editor in the GitHub issue about the completion
 
@@ -37,7 +36,7 @@ Codecheckers should give feedback to the author and definetely allow workflows t
 It is very hard to put a precise number on the amount of work you should put into a CODECHECK.
 You're not expected to spend more time on a CODECHECK than you would on peer-reviewing a manuscript.
 You should take advantage of the fact that you can _talk to the author_ and feel free to reach out early and often, when you think that issues can be resolved quickly.
-Depending on your familiarity with the used programming language and specific tools at hand, a very rough experience value could be 30 minutes of reading documentation, downloading and installing software, and another 30 minutes to write up the CODECHECK report.
+Depending on your familiarity with the used programming language and specific tools at hand, a very rough experience value could be 30 minutes of reading documentation, downloading and installing software, and another 30 minutes to write up the CODECHECK certificate.
 The time in between for running the actual workflow will vary greatly, from minutes to hours, and hopefully can be run in the background.
 In case the computations run longer than your regular working day, consider asking the author to prepare a subset of the workflow.
 
@@ -59,48 +58,49 @@ Some further tips:
   You can use `.codecheck` if `codecheck` exists in submission for some reason.
   _All files created by you go into this directory._
   The exception are files that the author could have used and which you suggest the author transfers into her own repository after the check (see "leave in a better condition" above).
-1. **Write a `Makefile`** to re-run the workflow based on provided documentation, i.e., recreate all files listed in the manifest by runnign the command `make codecheck`.
-  This target should run the whole or most suitable subset of the workflow and create the report.
-1. **Optional contents** of the check directory.
-    - Document the used computing environment, see [CODECHECK bundle guide](/guide/bundle).
-    - Create a notebook as the basis for the report (see below), e.g. `codecheck.Rmd`.
-    - Make the repository [Binder-ready](https://mybinder.readthedocs.io/); put all Binder-related files into `.binder/` directory to separate them from the author's content.
-1. **Write the CODECHECK report** and save it as a PDF file named **`codecheck.pdf`** in the check directory.
-  The report should cover at least _WHO_ checked _WHAT_, and _HOW_.
-  Imagine the report as a reminder for future you so you will be to re-check the workflow in two years time - what help would you need to do that?
-  Take a look at the [example CODECHECKs](#examples) for existing reports to serve as templates.
-1. **Optional report sections** depending on interest, time, and skills:
-    - _How to cite the report?_ Your CODECHECK is a valuable contribution to science, and you should add a short note on how to cite your report (see below for reserving the DOI).
-    - Do the generated outputs match the ones in the original manuscript? Are the differences relevant or not?
-    - Are there any parts of the workflow where the author could improve the code?
-    - How long did it take you to conduct the CHECK, and where did you struggle?
-    - Are used pieces of software and data properly CITED and publicly DEPOSITED und suitable LICENSES?
-    - Are open formats (text-based etc.) used for input and output data?
-    - Is the data and [software](https://content.iospress.com/articles/data-science/ds190026) FAIR?
-1. Add **mandatory codechecker-contributed information** to the **`codecheck.yml`** file, see [spec](/spec/config/latest)
-1. Wait for the article DOI.
-1. **Deposit the CODECHECK report on _Zenodo_** using your own Zenodo account
+    1. **Write a `Makefile`** to re-run the workflow based on provided documentation, i.e., recreate all files listed in the manifest by runnign the command `make codecheck`.
+      This target should run the whole or most suitable subset of the workflow and create the certificate.
+    1. **Optional contents** of the check directory.
+        - Document the used computing environment, see [CODECHECK bundle guide](/guide/bundle).
+        - Create a notebook as the basis for the certificate (see below), e.g. `codecheck.Rmd`.
+        - Make the repository [Binder-ready](https://mybinder.readthedocs.io/); put all Binder-related files into `.binder/` directory to separate them from the author's content.
+    1. **Write the CODECHECK certificate** and save it as a PDF file named **`codecheck.pdf`** in the check directory.
+      The certificate should cover at least _WHO_ checked _WHAT_, and _HOW_.
+      Imagine the certificate as a reminder for future you so you will be to re-check the workflow in two years time - what help would you need to do that?
+      Include a _full citation of the certificate_, because your CODECHECK is a valuable contribution to science (see below for reserving the DOI).
+      Take a look at the [example CODECHECKs](/guide/community-workflow-overview#examples) for existing certificates to serve as templates.
+    1. **Optional certificate sections** depending on interest, time, and skills:
+        - Do the generated outputs match the ones in the original manuscript? Are the differences relevant or not?
+        - Are there any parts of the workflow where the author could improve the code?
+        - How long did it take you to conduct the CHECK, and where did you struggle?
+        - Are used pieces of software and data properly CITED and publicly DEPOSITED und suitable LICENSES?
+        - Are open formats (text-based etc.) used for input and output data?
+        - Is the data and [software](https://content.iospress.com/articles/data-science/ds190026) FAIR?
+    1. Add **mandatory codechecker-contributed information** to the **`codecheck.yml`** file, see [spec](/spec/config/latest)
+    1. Wait for the article DOI.
+1. **Deposit the CODECHECK report on _Zenodo_** using your own Zenodo account.
+    - _Reserve a DOI_
+        - Add the DOI to the `codecheck.yml` file.
+        - Add the DOI to the `codecheck.pdf` CODECHECK report, which should include a full citation of itself.
     - _Files_
         - `codecheck.pdf` (mandatory)
-        - Optional: You can add any material to this record that you see fit, especially things that helped you with your reproduction, i.e., the [CODECHECK bundle](/guide/bundle)
-    - _Communities_: Search for "codecheck" to add the record to the [CODECHECK community on Zenodo](https://zenodo.org/communities/codecheck)
-    - _Authors_: Add all codecheckers as authors
-    - _Title_: `"CODECHECK Certificate YYYY-NNN"` (certificate number issued via the register ticket above)
-    - _License_: Use `Creative Commons Attribution 4.0 International` if you only upload the CODECHECK report, otherwise use `Other (Open)` or `Other (Attribution)` and document the licensing in the "Additional notes" field.
-    - _Reserve a DOI_
-        - Add the DOI to the `codecheck.yml` file
-        - Mention the DOI to the `codecheck.pdf` CODECHECK report, e.g. as a subtitle
-    - Use _other fields_ as you see fit (Description, Version, Language, Keywords)
-    - _Contributors_: Add the original authors as contributors (see Zendo Metadata form section "Contributors (optional)") with a suitable role (e.g., "Researcher")
-    - _Optionally_, add extra metadata
-        - connect the Zenodo record to the GitHub repository with a "Relate/alternate identifier"
-        - connect the Zenodo record to the article/preprint with a "Relate/alternate identifier"
-1. If the check was conducted for a piece of software for the first time or resulted in important lessons learned, consider adding it to the list of examples below.
-1. If possible, add the [CODE WORKS badge](https://github.com/codecheckers/website/tree/master/badges) <img src="/img/codeworks-badge.svg" alt="CODECHECK badge" height="16" style="margin-top: -4px;" /> to the article or the original software repository, e.g., by sending a pull request. The badge should link directly to the Zenodo record _via the DOI_.
-  The following snippet should work in Markdown:
-  
-  ```md
-  [![CODECHECK](https://codecheck.org.uk/img/codeworks-badge.svg)](https://doi.org/<DOI HERE>)
-  ```
-
+        - Optional: You can add any material to this record that you see fit, especially things that helped you with your reproduction, i.e., the [CODECHECK bundle](/guide/bundle).
+    - _Communities_: Search for "codecheck" to add the record to the [CODECHECK community on Zenodo](https://zenodo.org/communities/codecheck).
+    - _Authors_: Add all codecheckers as authors.
+    - _Title_: `"CODECHECK Certificate YYYY-NNN"` (certificate number issued via the register ticket above).
+    - _License_: Use `Creative Commons Attribution 4.0 International` if you only upload the CODECHECK report, otherwise use `Other (Open)` or `Other (Attribution)` and document the licensing of the different parts in an _Additional notes_ field.
+    - _Description_: Copy the summary of the check here.
+    - _Contributors_: Add the original authors as contributors (see Zendo Metadata form section "Contributors (optional)") with a suitable role (e.g., "Researcher").
+    - _Optionally_, add extra metadata as you see fit (fields such as _Version_, _Language_, _Keywords_).
+        - Connect the Zenodo record to the GitHub repository with a _Relate/alternate identifier_.
+        - Connect the Zenodo record to the article/preprint with a _Related/alternate identifier_.
+1. If the check was conducted for a piece of software for the first time or resulted in important lessons learned, please suggest it to the editor in the checks's GitHub issue.
 1. If the check material is published on `github.com/codecheckers`, add the [`codecheck` topic](https://github.com/search?q=topic%3Acodecheck+fork%3Atrue+org%3Acodecheckers&type=Repositories) to the project.
+1. If possible, add the [CODE WORKS badge](https://github.com/codecheckers/website/tree/master/badges) <img src="/img/codeworks-badge.svg" alt="CODECHECK badge" height="16" style="margin-top: -4px;" /> to the software repository, e.g., by sending a pull request.
+    The badge should link directly to the Zenodo record _via the DOI_.
+    The following snippet should work in Markdown:
+
+    ```md
+    [![CODECHECK](https://codecheck.org.uk/img/codeworks-badge.svg)](https://doi.org/<DOI HERE>)
+    ```
+
diff --git a/guide/community-workflow-overview.md b/guide/community-workflow-overview.md
@@ -18,7 +18,7 @@ The community workflow is a concrete implementation of the abstract [CODECHECK p
 The community workflow documentation is split into three parts:
 
 - [CODECHECK community workflow for authors](/guide/community-workflow-author)
-- [CODECHECK community workflow for codecheckers](/guide/community-workflow-author)
+- [CODECHECK community workflow for codecheckers](/guide/community-workflow-codechecker)
   This perspective also has variants: a focused version, a more detailed version, and a version for [in-person workshop with CHECK-NL](/nl/workflow)
 - [CODECHECK community workflow for editors](/guide/community-workflow-editor)
 
diff --git a/index.md b/index.md
@@ -35,6 +35,7 @@ CODECHECK is based on **five principles** which are described in detail in the [
 1. Workflows must be auditable.
 1. Open by default and transitional by disposition.
 
+The principles can be implemented in different [processes](/process/), one of which is the [CODECHECK community workflow](/guide/community-workflow-overview).
 **If you want to get involved as a codechecker in the community, or if you want to apply the CODECHECK principles in your journal or conference, please take a look at the [Get Involved](/get-involved) page.**
 
 To **stay in touch** with the project, follow us on social media at **<https://fediscience.org/@codecheck>**.
