OTT-402: Adds ruby installation guide

source/manual/get-started.html.md

@@ -206,7 +206,17 @@ While rebasing is generally acceptable during the development process, please en
 
 For more information on which repositories depend on merge commits, please refer to [this][generate-release-notes] script.
 
+## 12. A note on installing dependencies
+
+We use [asdf][asdf] to manage versions of programming languages and tools. This allows us to have multiple versions of the same tool installed on our machines.
+
+Our main languages are Ruby and Node.js, so you will need to install these with asdf.
+
+To keep up-to-date with ruby installations in each project you can follow the [ruby installation guide][ruby-installation].
+
 [generate-release-notes]: https://github.com/trade-tariff/trade-tariff-tools/blob/main/bin/generate_release_notes.sh
 [regression-chat]: https://future-borders.slack.com/archives/C02T8JXUYE9
 [developer-chat]: https://future-borders.slack.com/archives/C01DXUP15M5
 [infrastructure-chat]: https://future-borders.slack.com/archives/C042HGJBHK8
+[asdf]: https://asdf-vm.com/
+[ruby-installation]: /manual/ruby.html

source/manual/ruby.html.md

@@ -0,0 +1,77 @@
+---
+owner_slack: "#ott-core"
+title: Install ruby
+section: Applications
+layout: manual_layout
+parent: "/manual.html"
+---
+
+> We use `asdf` to manage multiple runtime versions. This guide will show you how to install `ruby` with `asdf`.
+
+## Prerequisites
+
+- Mac
+- [Homebrew][homebrew]
+- curl
+- git
+
+## Steps
+
+- Install `asdf` with homebrew
+- Install `ruby` with `asdf`
+- Enable a global version of `ruby` with `asdf`
+- Check your ruby version
+
+### Install `asdf` with homebrew
+
+```sh
+brew install asdf
+echo -e "\n. $(brew --prefix asdf)/libexec/asdf.sh" >> ${ZDOTDIR:-~}/.zshrc
+```
+
+### Install `ruby` with `asdf`
+
+```sh
+# Enable the ruby plugin in asdf
+asdf plugin add ruby
+# Find a ruby version you want
+asdf list-all ruby
+# Install the version you want
+asdf install ruby 3.0.2
+```
+
+### Enable a global version of `ruby` with `asdf`
+
+```sh
+# Enable a global version of ruby
+asdf global ruby 3.0.2
+```
+
+### Check your ruby version
+
+```sh
+ruby --version
+```
+
+## Project-specific ruby versions
+
+`asdf` offers support for a local file in a specific project to specify the version of ruby to use.
+
+This diminishes the chance of differences between your locally used version of ruby and the version installed
+in other environments from causing issues.
+
+This is all configured with `.tool-versions` in the root of each project repoistory
+
+For example, to specify the version of ruby to use in a project, create a `.tool-versions` file in the root of the project repository with the following content:
+
+```sh
+asdf local ruby 3.0.2
+```
+
+## Project-specific updates to ruby
+
+If you need to update the version of ruby in a project, update the `.tool-versions` file in the root of the project repository with the new version of ruby you want to use.
+
+Everyone that uses `asdf` can then just run `asdf install` in the project repository to install the new version of ruby.
+
+[homebrew]: https://brew.sh/