diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9112b5e615..9f2af30e05 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,10 +6,6 @@ Rules
 
 **Do not commit code changes to the master branch!**
 
-**Read the documentation on [submodules][]!**
-
-**Do not commit submodule updates accidentally!**
-
 Don't forget to commit early and often!
 
 Please add `[ci skip]` to commits that should be ignored by the CI systems
@@ -24,7 +20,6 @@ Write *good* commit messages. Follow Tim Pope's [guidelines][]:
 * The rest should be a wrapped, detailed explanation of the what and why
 * The tone should be imperative
 
-[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
 [guidelines]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
 
 New to Git?
@@ -71,7 +66,9 @@ Particularly:
 * Checkout a new local branch for every change you want to make (bugfix, feature).
 * Use `alias/feature-name` pattern.
 * Use lowercase-with-dashes for naming.
-* Use same branch name in super-project and all [submodules][].
+* Use same branch name in superproject and all [submodules][].
+
+[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
 
 Permissions
 -----------
@@ -87,29 +84,6 @@ repositories, as you can also just [fork a repo][].
 
 [fork a repo]: https://help.github.com/articles/fork-a-repo/
 
-Rebase and Fast-Forward Merge Pull Requests in Submodules
----------------------------------------------------------
-
-*This is not necessary in the superproject, only submodules!*
-
-Because GitHub's "Merge Pull Request" button merges with `--no-ff`, an
-extra merge commit will always be created. This can be especially
-annoying when trying to commit updates to submodules. Therefore our
-policy is to merge using the Git CLI after approval, with a rebase
-onto master to enable a fast-forward merge.
-
-Submodules
-----------
-
-This repository is a superproject with a half-dozen [submodules][].
-**DO NOT** commit updates unless absolutely necessary. When submodules
-must be updated, a separate Pull Request must be submitted, reviewed,
-and merged before updating the superproject. When committing submodule
-updates, ensure no other changes are in the same commit. Submodule
-bumps may be included in feature branches for ease of work, but the
-update must be independently approved before merging into master.
-
-
 Recommended Git configurations
 ------------------------------
 
diff --git a/docs/git/basics.md b/docs/git/basics.md
index 0bb36b0734..727958ea96 100644
--- a/docs/git/basics.md
+++ b/docs/git/basics.md
@@ -76,8 +76,8 @@ git fetch --all -p
 # you should call this command ONLY from master branch
 git pull origin master
 
-# update submodules
-git submodule update --recursive 
+# update submodules: this checks the submodules out to the commit recorded in the superproject
+git submodule update
 ```
 
 Then switch to your branch and do rebase
diff --git a/docs/git/committing.md b/docs/git/committing.md
index 305e64484a..555cff5bd1 100644
--- a/docs/git/committing.md
+++ b/docs/git/committing.md
@@ -1,8 +1,14 @@
-#Commit Dance
+Commit Dance
+============
 
-**Update:** commit dance became much simpler after [removing psl-monad submodule](https://github.com/PowerShell/PowerShell/issues/656).
-Meahwhile, there are still few submodules. If you need to touch their content, this doc provides the overview of the process.
-Remember that it's written against `src/monad` submodule, which doesn't exist anymore.
+**Update:** commit dance became much simpler after
+[removing psl-monad submodule](https://github.com/PowerShell/PowerShell/issues/656).
+Thus, this really only applies to `src/windows-build` and
+`src/Modules/Pester`. If you need to touch their content, this doc
+provides the overview of the process. Remember that it's written
+against `src/monad` submodule, which doesn't exist anymore.
+
+Also see the [submodules documentation](./submodules.md).
 
 Sometimes, you need to do the work in a submodule (i.e. you added a new string in `.resx` file).
 The submodule has a relationship to the SuperProject  (PowerShell), but in order to be sure that CI is
diff --git a/docs/git/submodules.md b/docs/git/submodules.md
new file mode 100644
index 0000000000..4626020262
--- /dev/null
+++ b/docs/git/submodules.md
@@ -0,0 +1,43 @@
+Submodules
+==========
+
+While most developers will not have to deal with submodules on a
+regular basis, those who do should read this information. The
+submodules currently in this project are:
+
+- `src/Modules/Pester`: The Pester testing framework for PowerShell
+
+- `src/libpsl-native/test/googletest`: The GoogleTest framework for
+  Linux native code
+
+- `src/windows-build`: Collection of pre-generated artifacts required
+  until .NET CLI deprecates them (C# resource bindings) and NuGet
+  packages that will soon be moved to a MyGet feed
+
+- `src/omi`: The Open Management Infrastructure project for PSRP on
+  Linux (to be removed)
+
+- `src/omi-provider`: The OMI provider for PSRP on Linux (to be
+  removed)
+
+[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
+
+Rebase and Fast-Forward Merge Pull Requests in Submodules
+=========================================================
+
+*This is not necessary in the superproject, only submodules!*
+
+**DO NOT** commit updates unless absolutely necessary. When submodules
+must be updated, a separate Pull Request must be submitted, reviewed,
+and merged before updating the superproject.
+
+Because GitHub's "Merge Pull Request" button merges with `--no-ff`, an
+extra merge commit will always be created. This is especially annoying
+when trying to commit updates to submodules. Therefore our policy is
+to merge using the Git CLI after approval, with a rebase onto master
+to enable a fast-forward merge.
+
+When committing submodule updates, ensure no other changes are in the
+same commit. Submodule bumps may be included in feature branches for
+ease of work, but the update must be independently approved before
+merging into master.