document vale, mlc

service/documentation.md

@@ -819,6 +819,28 @@ it's able to make changes inline.
 [nodejs markdownlint]: https://github.com/DavidAnson/markdownlint
 [codespell]: https://github.com/codespell-project/codespell/
 
+#### Vale
+
+Vale is interesting: it's used by both GitLab and Grafana to lint
+their documentation. Here are their (extensive) rule sets:
+
+ * [Grafana](https://github.com/grafana/writers-toolkit/tree/main/vale/Grafana)
+ * [GitLab](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/.vale/gitlab) (only one of the configurations, [their guide has
+   more](https://docs.gitlab.com/ee/development/documentation/testing/vale.html))
+
+In a brief test against a couple of pages in TPA's wiki, it finds a
+*lot* of spelling issues, mostly false positives (like `GitLab`, or
+`Grafana`), so we'd have to build a dictionary to not go bonkers. But
+it does find errors that codespell missed. We *could* bootstrap from
+[GitLab's dictionary](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/spelling-exceptions.txt), hooked from their [spelling rule](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/.vale/gitlab/Spelling.yml).
+
+#### mlc
+
+[mlc](https://github.com/becheran/mlc) was tested briefly as part of [the check links issue](https://gitlab.torproject.org/tpo/tpa/ci-templates/-/issues/14) and
+found to not handle internal GitLab wiki links properly (although that
+might be a problem for all link checkers that operate on the source
+code). It also [doesn't handle anchors](https://github.com/becheran/mlc/issues/31), so it was discarded.
+
 ### Charts and diagrams
 
 We currently use [Graphviz](https://graphviz.org/) to draw charts, but have also used