Use reference links rather than inline links

README.md

@@ -60,23 +60,29 @@ Some conventions are adopted and enforced, in no particular order:
 
 To release this very gem:
 
-1. Bump its version number in
-[`lib/alpine_lab/code_style/version.rb`](lib/alpine_lab/code_style/version.rb)
-according to [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html)
+1. Bump its version number in [`version.rb`] respecting [Semantic Versioning 2]
 
 2. Use Bundler Rake task to build, tag and push the gem:
 
     ```shell
     rake release
     ```
 
-    _(with Docker, you need to have configured both
-    [Git authentication](https://github.com/alpinelab/docker-ruby-dev/blob/latest/RECIPES.md#git-authentication)
-    and [Rubygems authentication](https://github.com/alpinelab/docker-ruby-dev/blob/latest/RECIPES.md#rubygems-authentication)
-    then you can run the same command with `docker-compose run app rake release`)_
+    _(using Docker, both [Git authentication] and [Rubygems authentication] must
+    be configured to run `docker-compose run app rake release`)_
 
 ## License
 
-This project is developed by [Alpine Lab](https://www.alpine-lab.com) and released under the terms of the [MIT license](LICENSE.md).
+This project is developed by [Alpine Lab] and released under the terms of the
+[MIT license].
 
-<a href="https://www.alpine-lab.com"><img src=".github/alpinelab-logo.png" width="40%" /></a>
+<a href="https://www.alpine-lab.com">
+  <img src=".github/alpinelab-logo.png" width="40%" />
+</a>
+
+[Alpine Lab]: https://www.alpine-lab.com
+[git authentication]: https://github.com/alpinelab/docker-ruby-dev/blob/latest/RECIPES.md#git-authentication
+[MIT license]: LICENSE.md
+[RubyGems authentication]: https://github.com/alpinelab/docker-ruby-dev/blob/latest/RECIPES.md#rubygems-authentication
+[Semantic Versioning 2]: https://semver.org/spec/v2.0.0.html
+[`version.rb`]: lib/alpine_lab/code_style/version.rb

docs/http-api.md

@@ -2,22 +2,20 @@
 
 ## API description
 
-We use [OpenAPI Specification 2.0](https://swagger.io/specification/v2/)
-to describe our API.
+We use [OpenAPI Specification 2.0] to describe our API.
 
 This OAS 2.0 description is then used by:
-* [Dredd](https://github.com/apiaryio/dredd) to check our implementation
-* [Committee](https://github.com/interagent/committee) to validate input data
-* [SwaggerUI](https://swagger.io/tools/swagger-ui) to generate documentation
+* [Dredd] to check our implementation
+* [Committee] to validate input data
+* [SwaggerUI] to generate documentation
 
 ## JSON generation
 
-We use [jBuilder](https://github.com/rails/jbuilder) to write our JSON views.
+We use [jBuilder] to write our JSON views.
 
-We may use [Oj](https://github.com/ohler55/oj) to parse and marshall
-JSON on performance-demanding projects (`jBuilder` uses
-[MultiJSON](https://github.com/intridea/multi_json) that uses `Oj` as soon as
-it is required, so we simply have to add it to the project `Gemfile`).
+We may use [Oj] to parse and marshall JSON on performance-demanding projects
+([jBuilder] uses [MultiJSON] that uses [Oj] as soon as it is required,
+so we simply have to add it to the project `Gemfile`).
 
 ## Controllers segregation
 
@@ -28,9 +26,18 @@ Instead, we favour an approach where API controllers are namespaced in a module
 named `API` (_e.g._ `ResourcesController` processes HTML requests while
 `API::ResourcesController` processes JSON requests).
 
-It avoids unreadable controller actions with many `respond_to` and `format`,
-but is a bit less [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)
-because we basically need 2 controllers per resource.
-This should incentivise us to keep business logic separated in external modules
-like service classes, thus enforcing the
-[SRP](https://en.wikipedia.org/wiki/Single_responsibility_principle).
+It avoids unreadable controller actions with many calls to `respond_to` and
+`format`, but is a bit less [Don't Repeat Yourself] because we basically need
+two controllers per resource. On the other hand, it incentivises us to keep
+business logic separated in external modules like service classes,
+thus enforcing the [Single Responsibility Principle].
+
+[Committee]: https://github.com/interagent/committee
+[Don't Repeat Yourself]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
+[Dredd]: https://github.com/apiaryio/dredd
+[jBuilder]: https://github.com/rails/jbuilder
+[MultiJSON][https://github.com/intridea/multi_json]
+[Oj]: https://github.com/ohler55/oj
+[OpenAPI Specification 2.0]: https://swagger.io/specification/v2/
+[Single Responsibility Principle]: https://en.wikipedia.org/wiki/Single_responsibility_principle
+[SwaggeUI]: https://swagger.io/tools/swagger-ui