Move linters doc, improve intro

The introduction to the linters guide is rather thin. Improve it and
move to `guides/`.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

content/guidelines/add_linters_to_a_project.md → content/guides/add_linters_to_a_project.md

@@ -9,9 +9,14 @@ aliases = [
 ]
 +++
 
-To add code linters to a project
+Linters are tools that analyze the code and warn about bugs & style issues.
+Utilising such tools can help improve code quality and enforce a consistent
+style which can help with code maintainability and bug fixing, especially where
+multiple developers are likely to be maintaining the code.
 
-## Install clang-format-linter locally
+This guide shows how to utilise the clang linter.
+
+# Install clang-format-linter locally
 
 A custom local install of the linter for C, C++, Python and Bash/POSIX
 shell can be easily done.
@@ -24,15 +29,13 @@ Check the installation:
 
     arc linters  # should list ‘clang-format’ as ‘configured’
 
-## Add a .clang-format file
+# Add a .clang-format file
 
 clang-format accepts its [format
 options](http://clang.llvm.org/docs/ClangFormatStyleOptions.html) from a
 hidden file, defined in YAML format. Create `.clang-format` and commit
 it to git:
 
-See <https://designs.apertis.org/latest/coding_conventions.html#code-formatting>
-
     BasedOnStyle: GNU
     AlwaysBreakAfterDefinitionReturnType: All
     BreakBeforeBinaryOperators: None
@@ -44,12 +47,11 @@ conventions](https://designs.apertis.org/latest/coding_conventions.html#code-for
 but may change in future as clang-format evolves or corner cases in the
 configuration are found and fixed.
 
-## Add a .arclint file
+# Add a .arclint file
 
-To enable the linters to be used with `arc lint` (and hence with `arc
-diff` and `git-phab attach`), add a `.arclint` file to the project and
-commit it to git. This example file contains XML, Python and C linters.
-Note that you should adjust the `include` path for the
+To enable the linters to be used with `arc lint`, add a `.arclint` file to the
+project and commit it to git. This example file contains XML, Python and C
+linters.  Note that you should adjust the `include` path for the
 `clang-format-default` linter to include the source directories in your
 project, while excluding any generated C or H files.
 
@@ -77,17 +79,16 @@ project, while excluding any generated C or H files.
       }
     }
 
-We ignore PEP8 [error
-E402](http://pep8.readthedocs.org/en/latest/intro.html#error-codes)
-because the recommended copyright headers, editor modelines and encoding
-lines push the first `import` statement below the recommended line
-number [according to
-PEP8](https://www.python.org/dev/peps/pep-0008/#imports).
+We ignore PEP8
+[error E402](http://pep8.readthedocs.org/en/latest/intro.html#error-codes)
+because the recommended copyright headers, editor modelines and encoding lines
+push the first `import` statement below the recommended line number
+[according to PEP8](https://www.python.org/dev/peps/pep-0008/#imports).
 
-## Add a .gitlab-ci.yml file
+# Add a .gitlab-ci.yml file
 
-To run the linters automatically on GitLab CI as soon as a Merge Request
-is created, add a `.gitlab-ci.yml` file to the project:
+To run the linters automatically on GitLab CI as soon as a Merge Request is
+created, add a `.gitlab-ci.yml` file to the project:
 
     check_formatting:
       image: debian:buster