Add docs testing Make target and CI/CD joberead/add-docs-testing-make-target-and-ci_cd-job

Also expand reach of Markdown linting to more files

8 files changed, 144 insertions, 128 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index 63ef5f29f..8480915bb 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -290,6 +290,13 @@ test:fips:
       when: manual
       allow_failure: true
 
+verify:docs:
+  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-markdown:alpine-3.16-vale-2.20.2-markdownlint-0.32.2-markdownlint2-0.5.1
+  needs: []
+  stage: test
+  script:
+    - make lint-docs
+
 verify:
   needs: []
   stage: test
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a616c9d33..c1f79f8d5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,7 +6,8 @@ Except for the license granted herein to GitLab B.V. and recipients of software
 distributed by GitLab B.V., you reserve all right, title, and interest in and to
 your Contributions.
 
-All contributions are subject to the Developer Certificate of Origin and license set out at [docs.gitlab.com/ce/legal/developer_certificate_of_origin](https://docs.gitlab.com/ce/legal/developer_certificate_of_origin).
+All contributions are subject to the
+[Developer Certificate of Origin and License](https://docs.gitlab.com/ee/legal/developer_certificate_of_origin).
 
 _This notice should stay as the first item in the CONTRIBUTING.md file._
 
@@ -225,7 +226,7 @@ Signed-off-by: Alice <alice@example.com>
 ## Gitaly Maintainers
 
 This project is maintained by the [members](https://gitlab.com/groups/gl-gitaly/-/group_members)
-of @gl-gitaly.
+of `@gl-gitaly`.
 
 ## Development Process
 
@@ -251,15 +252,15 @@ See the [beginner's guide](doc/beginners_guide.md).
 
 ## Debug Logging
 
-Debug logging can be enabled in Gitaly using `level = "debug"` under `[logging]` in config.toml.
+Debug logging can be enabled in Gitaly using `level = "debug"` under `[logging]` in `config.toml`.
 
 ## Git Tracing
 
 Gitaly will reexport `GIT_TRACE*` [environment variables](https://git-scm.com/book/en/v2/Git-Internals-Environment-Variables) if they are set.
 
-This can be an aid to debugging some sets of problems. For example, if you would like to know what git is doing internally, you can set `GIT_TRACE=true`:
+This can be an aid to debugging some sets of problems. For example, if you would like to know what Git is doing internally, you can set `GIT_TRACE=true`:
 
-Note that since git stderr stream will be logged at debug level, you need to enable debug logging in `config.toml`.
+Note that since Git stderr stream will be logged at debug level, you need to enable debug logging in `config.toml`.
 
 ```shell
 $ GIT_TRACE=true ./gitaly config.toml
@@ -283,7 +284,7 @@ DEBU[0037] 13:04:31.079286 git.c:322               trace: built-in: git 'rerere'
 
 ## Testing with Instrumentation
 
-If you would like to test with instrumentation and prometheus metrics, use the `instrumented-cluster` docker compose configuration in
+If you would like to test with instrumentation and Prometheus metrics, use the `instrumented-cluster` Docker compose configuration in
 `_support/instrumented-cluster`. This cluster will create several services:
 
 |*Service*|*Endpoint*|
@@ -294,7 +295,7 @@ If you would like to test with instrumentation and prometheus metrics, use the `
 | cAdvisor | [http://localhost:8080](http://localhost:8080) |
 | Grafana | [http://localhost:3000](http://localhost:3000) use default login `admin`/`admin` |
 
-The gitaly service uses the `gitlab/gitaly:latest` image, which you need to build using `make docker` before starting the cluster.
+The Gitaly service uses the `gitlab/gitaly:latest` image, which you need to build using `make docker` before starting the cluster.
 
 Once you have the `gitlab/gitaly:latest` image, start the cluster from the `_support/instrumented-cluster` directory using:
 
@@ -308,7 +309,7 @@ Note that the Gitaly service is intentionally limited to 50% CPU and 200MB of me
 
 Once the cluster has started, it will clone the `gitlab-org/gitlab-ce` repository, for testing purposes.
 
-This can then be used for testing, using tools like [gitaly-bench](https://gitlab.com/gitlab-org/gitaly-bench):
+This can then be used for testing, using tools like [`gitaly-bench`](https://gitlab.com/gitlab-org/gitaly-bench):
 
 ```shell
 gitaly-bench -concurrency 100 -repo gitlab-org/gitlab-ce.git find-all-branches
diff --git a/Makefile b/Makefile
index 10e1a3222..b44e50896 100644
--- a/Makefile
+++ b/Makefile
@@ -427,6 +427,11 @@ lint: ${GOLANGCI_LINT} libgit2 ${GITALY_PACKED_EXECUTABLES}
 lint-fix: ${GOLANGCI_LINT} libgit2 ${GITALY_PACKED_EXECUTABLES}
 	${Q}${GOLANGCI_LINT} run --fix --build-tags "${SERVER_BUILD_TAGS},${GIT2GO_BUILD_TAGS}" --out-format tab --config ${GOLANGCI_LINT_CONFIG} ${GOLANGCI_LINT_OPTIONS}
 
+.PHONY: lint-docs
+## Run Markdownlint to lint documentation.
+lint-docs:
+	${Q}markdownlint-cli2-config .markdownlint.yml README.md REVIEWING.md STYLE.md **/*.md || (echo "error: markdownlint-cli2 not found!")
+
 .PHONY: format
 ## Run Go formatter and adjust imports.
 format: ${GOIMPORTS} ${GOFUMPT}
diff --git a/README.md b/README.md
index c3e16f2cc..17e7993ad 100644
--- a/README.md
+++ b/README.md
@@ -6,21 +6,19 @@
   [GitLab Gitaly Issues](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&state=opened&label_name%5B%5D=Gitaly) |
   [GitLab Gitaly Merge Requests](https://gitlab.com/groups/gitlab-org/-/merge_requests?label_name%5B%5D=Gitaly) |
 
---------------------------------------------
-
 Gitaly is a Git [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call)
-service for handling all the git calls made by GitLab.
+service for handling all the Git calls made by GitLab.
 
 To see where it fits in please look at [GitLab's architecture](https://docs.gitlab.com/ce/development/architecture.html#system-layout).
 
 ## Project Goals
 
-Fault-tolerant horizontal scaling of Git storage in GitLab, and particularly, on [gitlab.com](https://gitlab.com).
+Fault-tolerant horizontal scaling of Git storage in GitLab, and particularly, on [GitLab.com](https://gitlab.com).
 
 This will be achieved by focusing on two areas (in this order):
 
-  1. **Migrate from repository access via NFS to gitaly-proto, GitLab's new Git RPC protocol**
-  1. **Evolve from large Gitaly servers managed as "pets" to smaller Gitaly servers that are "cattle"**
+1. **Migrate from repository access via NFS to `gitaly-proto`, GitLab's new Git RPC protocol**
+1. **Evolve from large Gitaly servers managed as "pets" to smaller Gitaly servers that are "cattle"**
 
 ## Current Status
 
@@ -33,21 +31,20 @@ removed](https://about.gitlab.com/2018/09/12/the-road-to-gitaly-1-0/).
 For performance reasons some RPCs can be performed through NFS still. An
 effort is made to mitigate performance issues by removing [Gitaly N+1](https://gitlab.com/groups/gitlab-org/-/epics/827).
 Once that is no longer necessary we can conclude the migration project by
-[removing the Git repository storage paths from gitlab-rails's
-configuration](https://gitlab.com/gitlab-org/gitaly/issues/1282).
+[removing the Git repository storage paths from GitLab Rails configuration](https://gitlab.com/gitlab-org/gitaly/issues/1282).
 
 In the meantime we are building features according to our [roadmap][roadmap].
 
 If you're interested in seeing how well Gitaly is performing on
 GitLab.com, read about our [observability story](doc/observability.md)!
 
-##### Overall
+### Overall
 
 ![image](https://gitlab.com/gitlab-org/gitaly/uploads/c3aa987884d5e78c3567a3a7469ea6c2/overview.png)
 
 [Dashboard](https://dashboards.gitlab.net/d/gitaly-main/gitaly-overview) (The link can be accessed by GitLab team members.)
 
-##### By Feature
+### By Feature
 
 ![image](https://gitlab.com/gitlab-org/gitaly/uploads/3e8a5616863fa17c5bf08cb67c1bb385/feature.png)
 
@@ -73,10 +70,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Name
 
-Gitaly is a tribute to git and the town of [Aly](https://en.wikipedia.org/wiki/Aly). Where the town of
+Gitaly is a tribute to Git and the town of [Aly](https://en.wikipedia.org/wiki/Aly). Where the town of
 Aly has zero inhabitants most of the year we would like to reduce the number of
 disk operations to zero for most actions. It doesn't hurt that it sounds like
-Italy, the capital of which is [the destination of all roads](https://en.wikipedia.org/wiki/All_roads_lead_to_Rome). All git actions in
+Italy, the capital of which is [the destination of all roads](https://en.wikipedia.org/wiki/All_roads_lead_to_Rome). All Git actions in
 GitLab end up in Gitaly.
 
 ## Design
@@ -91,23 +88,23 @@ High-level architecture overview:
 
 As of Q4 2018, the following GitLab components act as Gitaly clients:
 
--   [gitlab-rails](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/gitaly_client.rb):
-    the main GitLab Rails application.
--   [gitlab-shell](https://gitlab.com/gitlab-org/gitlab-shell/tree/master):
-    for `git clone`, `git push` etc. via SSH.
--   [gitlab-workhorse](https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/internal/gitaly/gitaly.go):
-    for `git clone` via HTTPS and for slow requests that serve raw Git
-    data.
-    ([example](https://gitlab.com/gitlab-org/gitaly/raw/master/README.md))
--   [gitaly-ssh](https://gitlab.com/gitlab-org/gitaly/tree/master/cmd/gitaly-ssh):
-    for internal Git data transfers between Gitaly servers.
--   [gitaly-ruby](https://gitlab.com/gitlab-org/gitaly/blob/master/ruby/lib/gitlab/git/gitaly_remote_repository.rb):
-    for RPC's that interact with more than one repository, such as
-    merging a branch.
-
-The clients written in Go (gitlab-shell, gitlab-workhorse, gitaly-ssh)
+- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/gitlab/gitaly_client.rb):
+  the main GitLab Rails application.
+- [`gitlab-shell`](https://gitlab.com/gitlab-org/gitlab-shell/tree/main):
+  for `git clone`, `git push` etc. via SSH.
+- [`gitlab-workhorse`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/workhorse/internal/gitaly/gitaly.go):
+  for `git clone` via HTTPS and for slow requests that serve raw Git
+  data.
+  ([example](https://gitlab.com/gitlab-org/gitaly/raw/master/README.md))
+- [`gitaly-ssh`](https://gitlab.com/gitlab-org/gitaly/tree/master/cmd/gitaly-ssh):
+  for internal Git data transfers between Gitaly servers.
+- [`gitaly-ruby`](https://gitlab.com/gitlab-org/gitaly/blob/master/ruby/lib/gitlab/git/gitaly_remote_repository.rb):
+  for RPC's that interact with more than one repository, such as
+  merging a branch.
+
+The clients written in Go (`gitlab-shell`, `gitlab-workhorse`, `gitaly-ssh`)
 use library code from the
-[gitlab.com/gitlab-org/gitaly/client](https://gitlab.com/gitlab-org/gitaly/tree/master/client)
+[`gitlab.com/gitlab-org/gitaly/client`](https://gitlab.com/gitlab-org/gitaly/tree/master/client)
 package.
 
 ## High Availability
@@ -123,13 +120,13 @@ Praefect, which is hosted alongside the rest of Gitaly in this
 repository. As we currently envision it, Praefect will have four
 responsibilities:
 
--   route RPC traffic to the primary Gitaly server
--   inspect RPC traffic and mark repositories as dirty if the RPC is a
-    "mutator"
--   ensure dirty repositories have their changes replicated to the
-    secondary Gitaly servers
--   in the event of a failure on the primary, demote it to secondary and
-    elect a new primary
+- route RPC traffic to the primary Gitaly server
+- inspect RPC traffic and mark repositories as dirty if the RPC is a
+  "mutator"
+- ensure dirty repositories have their changes replicated to the
+  secondary Gitaly servers
+- in the event of a failure on the primary, demote it to secondary and
+  elect a new primary
 
 Praefect has internal state: it needs to be able to "remember" which
 repositories are in need of replication, and which Gitaly server is the
@@ -152,7 +149,7 @@ By default, no tracing implementation is linked into the binary, but different O
 For more details of the supported providers, see LabKit, but as an example, for Jaeger tracing support, include the tags: `BUILD_TAGS="tracer_static tracer_static_jaeger"`.
 
 ```shell
-$ make BUILD_TAGS="tracer_static tracer_static_jaeger"
+make BUILD_TAGS="tracer_static tracer_static_jaeger"
 ```
 
 Once Gitaly is compiled with an opentracing provider, the tracing configuration is configured via the `GITLAB_TRACING` environment variable.
@@ -170,75 +167,75 @@ Gitaly supports Continuous Profiling through [LabKit][] using [Stackdriver Profi
 For more information on how to set it up, see the [LabKit monitoring docs](https://gitlab.com/gitlab-org/labkit/-/blob/master/monitoring/doc.go).
 
 ## Presentations
+
 - [Praefect code walkthrough](https://youtu.be/w2R4ptDLPH4)
 
-    A walkthrough of the Praefect codebase.
+  A walkthrough of the Praefect codebase.
 
 - [How to configure backpressure in Gitaly](https://youtu.be/wX9CtFdLYxE)
 
-    An overview of the knobs in the Gitaly config to set limits on incoming traffic.
-    There is also [written documentation](doc/backpressure.md).
+  An overview of the knobs in the Gitaly config to set limits on incoming traffic.
+  There is also [written documentation](doc/backpressure.md).
 
 - [How Gitaly fits into GitLab (Youtube)](https://www.youtube.com/playlist?list=PL05JrBw4t0KqoFUiX42JG7BAc7pipMBAy) - a series of 1-hour training videos for contributors new to GitLab and Gitaly.
-  - [Part 1: the Gitaly client in gitlab-ce, 2019-02-21](https://www.youtube.com/watch?v=j0HNiKCnLTI&list=PL05JrBw4t0KqoFUiX42JG7BAc7pipMBAy)
+  - [Part 1: the Gitaly client in `gitlab-ce`, 2019-02-21](https://www.youtube.com/watch?v=j0HNiKCnLTI&list=PL05JrBw4t0KqoFUiX42JG7BAc7pipMBAy)
 
-      Overview of GitLab backend processes, gitlab-rails deep dive: Gitaly
-      config in gitlab-rails, SQL data model, overview of how Gitaly calls get
-      made via GitalyClient.call.
+    Overview of GitLab backend processes, GitLab Rails deep dive: Gitaly
+    config in GitLab Rails, SQL data model, overview of how Gitaly calls get
+    made via GitalyClient.call.
 
   - [Part 2: Git SSH, 2019-02-28](https://www.youtube.com/watch?v=0kY0HPFn25o&list=PL05JrBw4t0KqoFUiX42JG7BAc7pipMBAy)
 
-      What is in a gitaly-proto Repository message, legacy vs
-      hashed storage (repository directories), `git clone` via SSH,
-      gitlab-shell, `authorized_keys` and forced commands, what happens
-      during `git push`.
+    What is in a `gitaly-proto` Repository message, legacy vs
+    hashed storage (repository directories), `git clone` via SSH,
+    `gitlab-shell`, `authorized_keys` and forced commands, what happens
+    during `git push`.
 
   - [Part 3: Git push, 2019-03-07](https://www.youtube.com/watch?v=-kXYycFYDzo&list=PL05JrBw4t0KqoFUiX42JG7BAc7pipMBAy)
 
-      A closer look at the final stage of `git push` where the git hooks run
-      and the refs get updated. Interaction between the git hooks and GitLab
-      internal API. The Git
-      [object quarantine mechanism](https://git-scm.com/docs/git-receive-pack#_quarantine_environment).
-      Preview of Git HTTP (to be discussed next time).
+    A closer look at the final stage of `git push` where the Git hooks run
+    and the refs get updated. Interaction between the Git hooks and GitLab
+    internal API. The Git
+    [object quarantine mechanism](https://git-scm.com/docs/git-receive-pack#_quarantine_environment).
+    Preview of Git HTTP (to be discussed next time).
 
   - [Part 4: Git HTTP, 2019-03-14](https://www.youtube.com/watch?v=lM13p8lCu8A&list=PL05JrBw4t0KqoFUiX42JG7BAc7pipMBAy)
 
-      Intercepting Git HTTP traffic with mitmproxy, overview of
-      Git HTTP clone steps, code walk in gitlab-workhorse and gitlab-ce,
-      investigating internal workhorse API messages used for Git HTTP.
+    Intercepting Git HTTP traffic with mitmproxy, overview of
+    Git HTTP clone steps, code walk in `gitlab-workhorse` and `gitlab-ce`,
+    investigating internal workhorse API messages used for Git HTTP.
 
   - [Part 5: Merge Requests across Forks, 2019-03-21](https://www.youtube.com/watch?v=yGSuOz0XOHQ&list=PL05JrBw4t0KqoFUiX42JG7BAc7pipMBAy)
 
-      Fixing a locally broken Ruby gem C
-      extension by recompiling, demo of how creating a MR across forks
-      causes new commits to suddenly appear in the fork parent repository,
-      deep dive into the FetchSourceBranch RPC, adding debug code to see
-      how address and authentication metadata is passed down to
-      gitaly-ruby, failed attempt to log gitaly-ssh arguments, comparison
-      of gitaly-ssh and gitlab-shell, a Gitaly server can end up making RPC calls to itself.
-
-  -  [Part 6: Creating Git commits on behalf of Git users, 2019-03-21](https://www.youtube.com/watch?v=Rbe0KGTLkxY&list=PL05JrBw4t0KqoFUiX42JG7BAc7pipMBAy)
-
-      Demonstrate how usually Git hooks are run by
-      `git-receive-pack`, but sometimes by `gitaly-ruby`. Deep dive into
-      UserCommitFiles: where do those hooks actually get run? A look at
-      UserMerge. How does Gitaly make merge commits. A look at the
-      implementation of the special feature where users are not allowed
-      push to a branch, but are allowed to merge into it.
-
-  -  [Part 7: How Gitaly uses Prometheus monitoring, 2019-07-09](https://youtu.be/R6F674Nj3wI)
-
-      What is [Prometheus](https://prometheus.io/). Reconstructing a
-     [Grafana](https://dashboards.gitlab.net) dashboard panel
-      with
-      [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/).
-      Adding a new counter to Gitaly. Querying Prometheus in Gitaly
-      during development. Comparing latency calculation with
-      [ELK](https://log.gitlab.net). [GRPC Prometheus
-      middleware](https://github.com/grpc-ecosystem/go-grpc-prometheus)
-      in Gitaly.
-
-- [TheConf talk on Scaling GitLab git storage with Gitaly, 2019-08-16](https://speakerdeck.com/olsfer/how-gitlab-scaled-git-access-with-a-go-service)
+    Fixing a locally broken Ruby gem C
+    extension by recompiling, demo of how creating a MR across forks
+    causes new commits to suddenly appear in the fork parent repository,
+    deep dive into the FetchSourceBranch RPC, adding debug code to see
+    how address and authentication metadata is passed down to
+    `gitaly-ruby`, failed attempt to log `gitaly-ssh` arguments, comparison
+    of `gitaly-ssh` and `gitlab-shell`, a Gitaly server can end up making RPC calls to itself.
+
+  - [Part 6: Creating Git commits on behalf of Git users, 2019-03-21](https://www.youtube.com/watch?v=Rbe0KGTLkxY&list=PL05JrBw4t0KqoFUiX42JG7BAc7pipMBAy)
+
+    Demonstrate how usually Git hooks are run by
+    `git-receive-pack`, but sometimes by `gitaly-ruby`. Deep dive into
+    UserCommitFiles: where do those hooks actually get run? A look at
+    UserMerge. How does Gitaly make merge commits. A look at the
+    implementation of the special feature where users are not allowed
+    push to a branch, but are allowed to merge into it.
+
+  - [Part 7: How Gitaly uses Prometheus monitoring, 2019-07-09](https://youtu.be/R6F674Nj3wI)
+
+    What is [Prometheus](https://prometheus.io/). Reconstructing a
+    [Grafana](https://dashboards.gitlab.net) dashboard panel
+    with [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/).
+    Adding a new counter to Gitaly. Querying Prometheus in Gitaly
+    during development. Comparing latency calculation with
+    [ELK](https://log.gitlab.net). [GRPC Prometheus
+    middleware](https://github.com/grpc-ecosystem/go-grpc-prometheus)
+    in Gitaly.
+
+- [TheConf talk on Scaling GitLab Git storage with Gitaly, 2019-08-16](https://speakerdeck.com/olsfer/how-gitlab-scaled-git-access-with-a-go-service)
 - [Infrastructure Team Update 2017-05-11](https://about.gitlab.com/2017/05/11/functional-group-updates/#infrastructure-team)
 - [Gitaly Basics, 2017-05-01](https://docs.google.com/presentation/d/1cLslUbXVkniOaeJ-r3s5AYF0kQep8VeNfvs0XSGrpA0/edit#slide=id.g1c73db867d_0_0)
 - [Git Paris meetup, 2017-02-22](https://docs.google.com/presentation/d/19OZUalFMIDM8WujXrrIyCuVb_oVeaUzpb-UdGThOvAo/edit?usp=sharing) a high-level overview of what our plans are and where we are.
diff --git a/REVIEWING.md b/REVIEWING.md
index 18257dc06..5eafdaafb 100644
--- a/REVIEWING.md
+++ b/REVIEWING.md
@@ -15,11 +15,12 @@ one reviewer.
 When a merge request is created, Danger bot will suggest two people for
 review. To spread the load across the team, it's generally recommended to assign
 these two for review. But it's not uncommon to swap out one or two of them when:
+
 - they are OOO
 - they know the context of the change already
 
 The complete list of eligible reviewers can be found at:
-https://about.gitlab.com/handbook/engineering/projects/#gitaly_assignments
+<https://about.gitlab.com/handbook/engineering/projects/#gitaly_assignments>
 
 For small changes it's fine to only chose one person for review. The contributor
 can ask the reviewer if they are okay with this.
@@ -41,7 +42,7 @@ outage, because causing an outage is not the right thing to do.
 Goals of these tips:
 
 1. Streamline the review and acceptance process: improve throughput
-2. Ensure a thorough review: minimize the number of problems that are discovered after merging
+1. Ensure a thorough review: minimize the number of problems that are discovered after merging
 
 ### Tips for the Contributor
 
@@ -127,6 +128,7 @@ You finished a review round and you are about to submit your review with the
 problem in the MR?
 
 For example:
+
 - the MR is solving the wrong problem
 - the MR is making a backwards incompatible change
 - the MR has a test that does not test the right thing
diff --git a/STYLE.md b/STYLE.md
index 3b2ee4b79..cb4e72a71 100644
--- a/STYLE.md
+++ b/STYLE.md
@@ -14,7 +14,9 @@ code is accessible to different developers with varying setups.
 
 Use `%w` when wrapping errors with context.
 
-    fmt.Errorf("foo context: %w", err)
+```go
+fmt.Errorf("foo context: %w", err)
+```
 
 It allows to inspect the wrapped error by the caller with [`errors.As`](https://golang.org/pkg/errors/#As) and [`errors.Is`](https://golang.org/pkg/errors/#Is). More info about `errors` package capabilities could be found in the [blog post](https://blog.golang.org/go1.13-errors).
 
@@ -24,11 +26,13 @@ It is customary in Go to pass errors up the call stack and decorate
 them. To be a good neighbor to the rest of the call stack we should keep
 our errors short.
 
-    // Good
-    fmt.Errorf("peek diff line: %w", err)
+```go
+// Good
+fmt.Errorf("peek diff line: %w", err)
 
-    // Too long
-    fmt.Errorf("ParseDiffOutput: Unexpected error while peeking: %w", err)
+// Too long
+fmt.Errorf("ParseDiffOutput: Unexpected error while peeking: %w", err)
+```
 
 ### Use lower case in errors
 
@@ -211,9 +215,9 @@ func testHelper(tb testing.TB, ctx context.Context) {
 
 We like table-driven tests ([Table-driven tests using subtests](https://blog.golang.org/subtests#TOC_4.), [Cheney blog post], [Golang wiki]).
 
--   Use [subtests](https://blog.golang.org/subtests#TOC_4.) with your table-driven tests, using `t.Run`:
+- Use [subtests](https://blog.golang.org/subtests#TOC_4.) with your table-driven tests, using `t.Run`:
 
-```
+```go
 func TestTime(t *testing.T) {
     testCases := []struct {
         gmt  string
@@ -302,7 +306,7 @@ be implemented in a file called `testhelper_test.go`
 
 ## Git Commands
 
-Gitaly relies heavily on spawning git subprocesses to perform work. Any git
+Gitaly relies heavily on spawning Git subprocesses to perform work. Any Git
 commands spawned from Go code should use the constructs found in
 [`safecmd.go`](internal/git/safecmd.go). These constructs, all beginning with
 `Safe`, help prevent certain kinds of flag injection exploits. Proper usage is
@@ -310,15 +314,15 @@ important to mitigate these injection risks:
 
 - When toggling an option, prefer a longer flag over a short flag for
   readability.
-	- Desired: `git.Flag{Name: "--long-flag"}` is easier to read and audit
-	- Undesired: `git.Flag{Name: "-L"}`
+  - Desired: `git.Flag{Name: "--long-flag"}` is easier to read and audit
+  - Undesired: `git.Flag{Name: "-L"}`
 - When providing a variable to configure a flag, make sure to include the
   variable after an equal sign
-	- Desired: `[]git.Flag{Name: "-a="+foo}` prevents flag injection
-	- Undesired: `[]git.Flag(Name: "-a"+foo)` allows flag injection
+  - Desired: `[]git.Flag{Name: "-a="+foo}` prevents flag injection
+  - Undesired: `[]git.Flag(Name: "-a"+foo)` allows flag injection
 - Always define a flag's name via a constant, never use a variable:
-	- Desired: `[]git.Flag{Name: "-a"}`
-	- Undesired: `[]git.Flag{Name: foo}` is ambiguous and difficult to audit
+  - Desired: `[]git.Flag{Name: "-a"}`
+  - Undesired: `[]git.Flag{Name: foo}` is ambiguous and difficult to audit
 
 ## Go Imports Style
 
@@ -332,13 +336,13 @@ Example of **valid** usage:
 
 ```go
 import (
-	"context"
-	"io"
-	"os/exec"
+    "context"
+    "io"
+    "os/exec"
 
-	"gitlab.com/gitlab-org/gitaly/internal/command"
-	"gitlab.com/gitlab-org/gitaly/internal/git/alternates"
-	"gitlab.com/gitlab-org/gitaly/internal/git/repository"
+    "gitlab.com/gitlab-org/gitaly/internal/command"
+    "gitlab.com/gitlab-org/gitaly/internal/git/alternates"
+    "gitlab.com/gitlab-org/gitaly/internal/git/repository"
 )
 ```
 
@@ -346,15 +350,15 @@ Example of **invalid** usage:
 
 ```go
 import (
-	"io"
-	"os/exec"
+    "io"
+    "os/exec"
 
-	"context"
+    "context"
 
-	"gitlab.com/gitlab-org/gitaly/internal/git/alternates"
-	"gitlab.com/gitlab-org/gitaly/internal/git/repository"
+    "gitlab.com/gitlab-org/gitaly/internal/git/alternates"
+    "gitlab.com/gitlab-org/gitaly/internal/git/repository"
 
-	"gitlab.com/gitlab-org/gitaly/internal/command"
+    "gitlab.com/gitlab-org/gitaly/internal/command"
 )
 ```
 
@@ -398,7 +402,7 @@ func (scs SuperCoolService) MyAwesomeRPC(ctx context.Context, r Request) error {
 
     go func() {
         defer close(done)    // signal when the goroutine returns
-	doWork(r)
+    doWork(r)
     }()
 
     return nil
diff --git a/auth/README.md b/auth/README.md
index b5dc6f568..b4c065ac2 100644
--- a/auth/README.md
+++ b/auth/README.md
@@ -1,7 +1,7 @@
 # Gitaly authentication middleware for Go
 
 This package contains code that plugs into
-github.com/grpc-ecosystem/go-grpc-middleware/auth to provide client
+`github.com/grpc-ecosystem/go-grpc-middleware/auth` to provide client
 and server authentication middleware for Gitaly.
 
 Gitaly has two authentication schemes.
diff --git a/ruby/README.md b/ruby/README.md
index 1ff0f473a..54fea399e 100644
--- a/ruby/README.md
+++ b/ruby/README.md
@@ -7,22 +7,22 @@ speed up the Gitaly migration project.
 
 ## Architecture
 
-Gitaly-ruby is a minimal Ruby gRPC service which should only receive
+`gitaly-ruby` is a minimal Ruby gRPC service which should only receive
 requests from its (Go) parent Gitaly process. The Gitaly parent
 handles authentication, logging, metrics, configuration file parsing
 etc.
 
 The Gitaly parent is also responsible for starting and (if necessary)
-restarting Gitaly-ruby.
+restarting `gitaly-ruby`.
 
 ## Authentication
 
-Gitaly-ruby listens on a Unix socket in a temporary directory with
+`gitaly-ruby` listens on a Unix socket in a temporary directory with
 mode 0700. It runs as the same user as the Gitaly parent process.
 
 ## Testing
 
-There are three sets of test that exercise gitaly-ruby:
+There are three sets of test that exercise `gitaly-ruby`:
 
 - Top-level Go integration tests
 - Rspec integration tests (`spec/gitaly`)
@@ -37,7 +37,7 @@ tests only, without recompiling the Go parts then do the following:
 
 ## Development
 
-Gitaly-ruby is only meant to be spawned by Gitaly itself. But, during
+`gitaly-ruby` is only meant to be spawned by Gitaly itself. But, during
 development you may want to try spawning it in a terminal yourself.
 You can do that with the following incantation: