diff --git a/docs/lint_errors.md b/docs/lint_errors.md
index 1caf8c203c..dc84477354 100644
--- a/docs/lint_errors.md
+++ b/docs/lint_errors.md
@@ -100,16 +100,6 @@ These tests look at `process.container` and `$GITHUB_REF` only if they are set.
 * Container tag / `$GITHUB_REF` must contain only numbers and dots
 * Tags and `$GITHUB_REF` must all match one another
 
-## Error #10 - Template TODO statement found ## {#10}
-
-The nf-core workflow template contains a number of comment lines with the following format:
-
-```groovy
-// TODO nf-core: Make some kind of change to the workflow here
-```
-
-This lint test runs through all files in the pipeline and searches for these lines.
-
 ## Error #14 - Pipeline schema syntax ## {#14}
 
 Pipelines should have a `nextflow_schema.json` file that describes the different pipeline parameters (eg. `params.something`, `--something`).
diff --git a/nf_core/lint/actions_lint.py b/nf_core/lint/actions_lint.py
index c3a18d337f..442bd9ad64 100644
--- a/nf_core/lint/actions_lint.py
+++ b/nf_core/lint/actions_lint.py
@@ -52,7 +52,7 @@ def actions_lint(self):
              steps:
                - run: yamllint $(find ${GITHUB_WORKSPACE} -type f -name "*.yml")
 
-    .. note::  These are minimal examples of the commands and YAML structure and are not complete
+    .. warning::  These are minimal examples of the commands and YAML structure and are not complete
                enough to be copied into the workflow file.
     """
     passed = []
diff --git a/nf_core/lint/conda_dockerfile.py b/nf_core/lint/conda_dockerfile.py
index 5b9f21a024..838493be71 100644
--- a/nf_core/lint/conda_dockerfile.py
+++ b/nf_core/lint/conda_dockerfile.py
@@ -34,7 +34,7 @@ def conda_dockerfile(self):
         * The linting tool compares the tag against the currently installed version of tools.
         * This line is not checked if running a development version of nf-core/tools.
 
-    .. seealso:: Additional lines and different metadata can be added to the ``Dockerfile``
+    .. tip:: Additional lines and different metadata can be added to the ``Dockerfile``
                  without causing this lint test to fail.
     """
 
diff --git a/nf_core/lint/pipeline_todos.py b/nf_core/lint/pipeline_todos.py
index 2512fcad32..c5cb907658 100644
--- a/nf_core/lint/pipeline_todos.py
+++ b/nf_core/lint/pipeline_todos.py
@@ -6,7 +6,29 @@
 
 
 def pipeline_todos(self):
-    """ Go through all template files looking for the string 'TODO nf-core:' """
+    """Check for nf-core *TODO* lines.
+
+    The nf-core workflow template contains a number of comment lines to help developers
+    of new pipelines know where they need to edit files and add content.
+    They typically have the following format:
+
+    .. code-block:: groovy
+
+        // TODO nf-core: Make some kind of change to the workflow here
+
+    ..or in markdown:
+
+    .. code-block:: html
+
+        <!-- TODO nf-core: Add some detail to the docs here -->
+
+    This lint test runs through all files in the pipeline and searches for these lines.
+    If any are found they will throw a warning.
+
+    .. tip:: Note that many GUI code editors have plugins to list all instances of *TODO*
+              in a given project directory. This is a very quick and convenient way to get
+              started on your pipeline!
+    """
     passed = []
     warned = []
     failed = []