Added notes on "Living with Submodules"

README.md

@@ -18,6 +18,7 @@
 
 ---
 
+- [Living with Submodules](#living-with-submodules)
 - [Content](#content)
   - [Content Files](#content-files)
     - [External Content Files](#external-content-files)
@@ -34,6 +35,26 @@
 - [Authors](#authors)
 - [License](#license)
 
+## Living with Submodules
+
+This Git repo has [Git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules). They are the subdirectories of `external/`. Each one is basically another Git repo, i.e. an external Git repo that just _looks_ like it's part of this Git repo. It's very easy to get Git into a confusing state when there are submodules. If you follow the following tips, you should probably be okay:
+
+1. Clone this repo using:
+   ```bash
+   git clone --recurse-submodules git@github.com:oceanprotocol/docs.git
+   ```
+1. Don't edit anything in the submodules (i.e. in `external/`). Instead, edit it over in the other Git repository and merge your changes over there.
+1. Get all the submodules up-to-date using:
+   ```bash
+   git submodule update --remote
+   ```
+   That will get each submodule up-to-date with the HEAD commit of some branch in a remote repository. Which branch? That's set in the `.gitmodules` file. You can check the current commit hashes of all the submodules using `git submodule status`
+1. Before doing any `git checkout ...` or other normal Git operations, do this:
+   ```bash
+   git config --global submodule.recurse true
+   ```
+   That's like adding the `--recurse-submodules` option to all those Git commands (except for `git clone`) so you don't have to.
+
 ## Content
 
 The documentation is split in multiple sections whose content lives in this repo: