service/documentation.md

@@ -39,6 +39,11 @@ To make changes there, just clone and push to this git repository:
 
     git clone git@gitlab.torproject.org:tpo/tpa/wiki-replica.git
 
+Make changes, and push. Note that a GitLab CI pipeline will check your
+changes and might warn you if you work on a file with syntax
+problems. Feel free to ignore those warnings that were already
+present, but do be careful at not adding new ones.
+
 Ideally, you should also setup linting locally, see below.
 
 ## Local linting configuration
@@ -212,6 +217,35 @@ considered the editor of the wiki, but any other contributors is
 strongly encouraged to contribute to the knowledge accumulating in the
 wiki.
 
+### Linting
+
+There is a basic linting check deployed in GitLab CI on the [wiki
+replica](https://gitlab.torproject.org/tpo/tpa/wiki-replica), which will run on pull requests and normal
+pushes. Naturally, it will not run when someone edits the wiki
+directly, as the replica does not pull automatically from the wiki
+(because of limitations in the free GitLab mirror implementation).
+
+Those checks are setup in the `.gitlab-ci.yml` file. There is a basic
+`test` job that will run whenever a Markdown (`.md`) file gets
+modified. There is a rather convoluted pipeline to ensure that it runs
+*only* on those files, which requires a separate Docker image and job
+to generate that file list, because the [`markdownlint/markdownlint`
+Docker image](https://hub.docker.com/r/markdownlint/markdownlint) doesn't ship with git (see [this discussion for
+details](https://forum.gitlab.com/t/ci-cd-pipeline-get-list-of-changed-files/26847/16?u=anarcat)).
+
+There's a separate job (`testall`) which runs every time and checks
+*all* markdown files.
+
+Because GitLab has this... [unusual syntax](https://docs.gitlab.com/ee/user/markdown.html#table-of-contents) for triggering the
+automatic table of contents display (`[[_TOC_]]`), we need to go
+through some hoops to silence those warnings. This implies that the
+`testall` job will always fail, as long as we use that specific macro.
+
+Those linting checks could eventually be expanded to do more things,
+like spell-checking and check for links outside of the current
+document. See the [alternatives considered](#alternatives-considered) section for a broader
+discussion on the next steps here.
+
 ## Issues
 
 There is no issue tracker specifically for this project, [File][] or