Documentation

docs/modules/1-description-benchmark-module.md → docs/available-modules/1-description-benchmark-module.md

@@ -1,3 +1,3 @@
-# Description
+# Description of a module
 
 A benchmark module compares the performance of different data analysis workflows based on module-specific, predefined metrics. It provides a specific set of input files (e.g., mass spectrometry files and a sequence database) and it requires specific workflow output files (e.g., identified peptides). Based on these workflow output files, metrics are calculated as defined by the module and can be compared to previously validated benchmark runs. As each benchmark module defines specific workflow input files and metrics, it evaluates only a limited set of characteristics of the data analysis workflow.

docs/modules/index.rst → docs/available-modules/index.rst

@@ -5,6 +5,6 @@ ProteoBench benchmark modules
 .. toctree::
    :caption: ProteoBench benchmark modules
    :glob:
-   :maxdepth: 2
+   :maxdepth: 3
 
    *

docs/modules/2-module-life-cycle.md → docs/general-information/2-module-life-cycle.md

@@ -11,30 +11,9 @@ Anybody can propose a new benchmark module, and discuss on the validity of curre
 
 ## Proposal
 
-*Module proposals are not accepted yet. If you are interested, stay tuned.*
-
-Proposals can be started by opening a thread on GitHub Discussions, using a specific template. One of the ProteoBench maintainers will be assigned as editor.  
-At least two reviewers, independent from both existing ProteoBench contributors and from the proposal submitters, should be contacted to review the proposal.
-
-Required information for a proposal:
-
-1. A **description of the new module**:
-    - Which aspect of proteomics data analysis is benchmarked?
-    - Added value compared to already existing modules?
-2. **Input data**:
-    - Provide a persistent identifier for the dataset (e.g., PXD, or DOI) (If this does not exist yet, publish the data on Zenodo and provide this DOI)
-    - Optionally, provide DOI to the dataset publication
-    - If only a subset of the referenced dataset is used, describe which subset.
-    - Describe why this dataset was selected.
-3. **Workflow output data** (data to be uploaded to ProteoBench for metric calculation)
-4. Specify the **minimal information needed from the workflow for metric calculation**. This can be an existing (standardized) file format, or a simple well-described CSV file.
-5. **Structured metadata**: Which information is needed to sufficiently describe each benchmark run (e.g., workflow parameters).
-6. **Metrics**:
-    - Description of the benchmark metrics
-    - Methodology for calculating benchmark metrics
-7. How can the metric for each benchmark run be shown in a **single visualization** (optionally add a mock figure)
-8. **External reviewers**: Optionally propose at least two reviewers (see above)
-9. Will you be able to work on the implementation (coding) yourself, with additional help from the ProteoBench maintainers?
+Anyone can start a discussion or more formally propose new module, as described in ["How to propose/discuss a new module" section](./3-module-proposal.md).
+
+The proposal will be public, and discussed with the community before being implemented. We are currently setting up a reviewing process through [GitHub discussions](https://github.com/orgs/Proteobench/discussions).
 
 ## Implementation
 

docs/general-information/3-module-proposal.md

@@ -0,0 +1,26 @@
+# How to propose/discuss a new module
+
+Anyone can start a discussion or more formally propose new module.
+
+Proposals can be started by opening a [discussion on GitHub](https://github.com/orgs/Proteobench/discussions/new?category=potential-new-module-to-discuss), using a specific template. One of the ProteoBench maintainers will be assigned as editor.  
+At least two reviewers, independent from both existing ProteoBench contributors and from the proposal submitters, should be contacted to review the proposal.
+
+Required information for a proposal:
+
+1. A **description of the new module**:
+    - Which aspect of proteomics data analysis is benchmarked?
+    - Added value compared to already existing modules?
+2. **Input data**:
+    - Provide a persistent identifier for the dataset (e.g., PXD, or DOI) (If this does not exist yet, publish the data on Zenodo and provide this DOI)
+    - Optionally, provide DOI to the dataset publication
+    - If only a subset of the referenced dataset is used, describe which subset.
+    - Describe why this dataset was selected.
+3. **Workflow output data** (data to be uploaded to ProteoBench for metric calculation)
+4. Specify the **minimal information needed from the workflow for metric calculation**. This can be an existing (standardized) file format, or a simple well-described CSV file.
+5. **Structured metadata**: Which information is needed to sufficiently describe each benchmark run (e.g., workflow parameters).
+6. **Metrics**:
+    - Description of the benchmark metrics
+    - Methodology for calculating benchmark metrics
+7. How can the metric for each benchmark run be shown in a **single visualization** (optionally add a mock figure)
+8. **External reviewers**: Optionally propose at least two reviewers (see above)
+9. Will you be able to work on the implementation (coding) yourself, with additional help from the ProteoBench maintainers?

docs/general-information/4-troubleshooting.md

@@ -0,0 +1,13 @@
+# Troubleshooting
+
+Please let us know if you have issues when using ProteoBench. You can:
+
+- create an issue [here](https://github.com/Proteobench/ProteoBench/issues/new/choose)
+- contact us by email [here](mailto:proteobench@eubic-ms.org?subject=ProteoBench_troubleshooting)
+
+You may also find a solution to your problem(s) here:
+
+## Stable Internet Connection
+
+Make sure you have a stable internet connection. We rely on syncing results from GitHub, 
+which can lead to connections errors, see [#259](https://github.com/Proteobench/ProteoBench/issues/259).

docs/general-information/index.rst

@@ -0,0 +1,11 @@
+#############################
+General information
+#############################
+
+.. toctree::
+    :caption: General information
+    :glob:
+    :maxdepth: 3
+
+    *
+

docs/index.rst

@@ -7,7 +7,8 @@ Overview of ProteoBench
     :glob:
 
     About <self>
-    Modules <modules/index.rst>
+    General information <general-information/index.rst>
+    Modules <available-modules/index.rst>
     Developer guide <developer-guide/index.rst>
     Contributing <contributing.rst>
     Changelog <changelog.rst>