add troubleshooting and faq pages

Author: nvnieuwk

docs/extras/faq.md

@@ -0,0 +1,21 @@
+# Frequently Asked Questions
+
+## What pipelines are great examples of nf-schema usage?
+
+Here's a list of pipelines that are considered great examples of nf-schema usage:
+
+1. [nf-core pipelines](https://nf-co.re/pipelines/)
+2. [Joon-Klaps/viralgenie](https://github.com/Joon-Klaps/viralgenie)
+3. [genomic-medicine-sweden/nallo](https://github.com/genomic-medicine-sweden/nallo)
+4. [nf-cmgg/smallvariants](https://github.com/nf-cmgg/smallvariants)
+5. And many more...
+
+Feel free to open a pull request to add more examples!
+
+## How can I contribute to nf-schema?
+
+Take a look at the [contribution instruction](../contributing/setup.md) to get started with contributing to nf-schema.
+
+## Where can I ask other questions?
+
+If you have a question that is not addressed in this FAQ, feel free to create an issue on the nf-schema repository [here](https://github.com/nextflow-io/nf-schema/issues) or ask your question in the `#nf-schema` Slack channel on the [Nextflow Slack](https://www.nextflow.io/slack-invite.html) or the [nf-core Slack](https://nf-co.re/join/slack)

docs/extras/troubleshooting.md

@@ -0,0 +1,23 @@
+# Troubleshooting
+
+This section of the documentation contains a couple of common errors encountered while implementing nf-schema or using pipelines with the plugin and how to solve them.
+
+## An integer value is failing because a string value was expected
+
+Pipelines often use some kind of identifier field in their sample sheet, that usually gets `string` as the expected input. This can cause some issues when using CSV and TSV sample sheets since the types of all values are automatically inferred for these file types. Meaning that a value in the `sample` field that has `123` as the value would result in an integer instead of a string. Following error would be shown in this case:
+
+```
+-> Entry 1: Error for field 'sample' (123): Value is [integer] but should be [string]
+```
+
+There are multiple ways to solve this issue as pipeline developers and as pipeline users. The solutions will be listed from best options to worst:
+
+### Pipeline user
+
+- Option 1: Use a YAML or JSON file as sample sheet if that is allowed by the pipeline and make sure to quote the value. (`'123'` in the case of the example above)
+- Option 2: Activate [lenient validation mode](../configuration/configuration.md#lenientmode). Keep in mind that this will enable lenient validation for **ALL** validations in the pipeline.
+
+### Pipeline developer
+
+- Option 1: Modify `"type": "string"` in the affected JSON schema to `"type": ["string", "integer"]`. Make sure that integer values don't break anything in your pipeline. The easiest way to ensure compatibility is to cast the value to a string after converting the sample sheet to a list.
+- Option 2: Enforce usage of JSON and YAML sample sheets by only allowing files ending in `.yml`, `.yaml` or `.json` to be used.

docs/migration_guide.md

@@ -36,7 +36,7 @@ Updating your pipeline can be done in a couple simple steps.
 
 ### Updating the name and version of the plugin
 
-The name and the version of the plugin should be updated from `nf-validation` to `nf-schema@2.0.0`:
+The name and the version of the plugin should be updated from `nf-validation` to any version of `nf-schema@2.x.x`:
 
 === "nf-validation"
 
@@ -50,7 +50,7 @@ The name and the version of the plugin should be updated from `nf-validation` to
 
     ```groovy
     plugins {
-        id 'nf-schema@2.0.0'
+        id 'nf-schema@2.x.x'
     }
     ```
 

mkdocs.yml

@@ -13,7 +13,7 @@ nav:
       - nextflow_schema/sample_sheet_schema_examples.md
   - Tutorials:
       - nextflow_schema/create_schema.md
-      - migration_guide.md
+      - Nf-validation migration guide: migration_guide.md
   - Reference:
       - nextflow_schema/nextflow_schema_specification.md
       - nextflow_schema/sample_sheet_schema_specification.md
@@ -25,6 +25,9 @@ nav:
       - Samplesheet parsing: samplesheets/samplesheetToList.md
       - Samplesheet examples: samplesheets/examples.md
       - Other validation: validate/validate.md
+  - Extras:
+      - FAQ: extras/faq.md
+      - extras/troubleshooting.md
   - Contributing:
       - contributing/setup.md