3 files changed, 193 insertions, 58 deletions
diff --git a/docs/examples/overlay-triplets-linux-dynamic.md b/docs/examples/overlay-triplets-linux-dynamic.md
index 6168d85e6..b2868e2fd 100644
--- a/docs/examples/overlay-triplets-linux-dynamic.md
+++ b/docs/examples/overlay-triplets-linux-dynamic.md
@@ -1,66 +1,41 @@
-# Overlay triplets example: build dynamic libraries on Linux
+# Overlay triplets example
 
-Using **vcpkg** you can build libraries for the following triplets:
+## Building dynamic libraries on Linux
 
-<div>
-    <ul style="columns: 3;">
-        <li> arm-uwp</li>
-        <li> arm-windows</li>
-        <li> arm64-uwp</li>
-        <li> arm64-windows</li>
-        <li> x86-uwp</li>
-        <li> x86-windows</li>
-        <li> x86-windows-static</li>
-        <li> x64-uwp</li>
-        <li> x64-linux</li>
-        <li> x64-osx</li>
-        <li> x64-windows</li>
-        <li> x64-windows-static</li>
-    </ul>
-</div>
+Using **vcpkg** you can build libraries for many configurations out of the box. However, this doesn't currently include shared libraries on Linux and Mac OS.
 
+This doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms! This document will guide you through creating your own custom triplets with `--overlay-triplets` to easily build dynamic libraries on Linux.
 
-
-By design **vcpkg** builds only static libraries for Linux and Mac OS.
-However, this doesn't mean that you cannot use **vcpkg** to build your dynamic libraries on these platforms.
-
-This document will guide you through creating your own custom triplets to build dynamic libraries on Linux using **vcpkg**.
-
-### Step 1: Create a folder to contain your custom triplets
-
-```
-~/vcpkg$ mkdir ../custom-triplets
-```
-
-### Step 2: Create the custom triplet files
+### Step 1: Create the custom triplet files
 
 To save time, copy the existing `x64-linux.cmake` triplet file.
 
-```
-~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-dynamic.cmake
+```sh
+~/git$ mkdir custom-triplets
+~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-dynamic.cmake
 ```
 
 And modify `custom-triplets/x64-linux-dynamic.cmake` to match the contents below:
-```
+```cmake
+# ~/git/custom-triplets/x64-linux-dynamic.cmake
 set(VCPKG_TARGET_ARCHITECTURE x64)
 set(VCPKG_CRT_LINKAGE dynamic)
-# Change VCPKG_LIBRARY_LINKAGE from static to dynamic
-set(VCPKG_LIBRARY_LINKAGE dynamic)
+set(VCPKG_LIBRARY_LINKAGE dynamic) # This changed from static to dynamic
 
 set(VCPKG_CMAKE_SYSTEM_NAME Linux)
 ```
 
-### Step 3: Use `--overlay-triplets` to build dynamic libraries
+### Step 2: Use `--overlay-triplets` to build dynamic libraries
 
 Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory. 
 
 ```
-./vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=../custom-triplets
+~/git$ vcpkg/vcpkg install sqlite3:x64-linux-dynamic --overlay-triplets=custom-triplets
 The following packages will be built and installed:
-    sqlite3[core]:x64-linux
+    sqlite3[core]:x64-linux-dynamic
 Starting package 1/1: sqlite3:x64-linux-dynamic
 Building package sqlite3[core]:x64-linux-dynamic...
--- Loading triplet configuration from: /home/custom-triplets/x64-linux-dynamic.cmake
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux-dynamic.cmake
 -- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
 -- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
 -- Applying patch fix-arm-uwp.patch
@@ -84,7 +59,7 @@ The package sqlite3:x64-linux-dynamic provides CMake targets:
     target_link_libraries(main PRIVATE sqlite3)
 ```
 
-Overlay triplets will add your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.
+Overlay triplets enables your custom triplet files when using `vcpkg install`, `vcpkg update`, `vcpkg upgrade`, and `vcpkg remove`.
 
 When using the `--overlay-triplets` option, a message like the following lets you know that a custom triplet is being used: 
 
@@ -94,40 +69,33 @@ When using the `--overlay-triplets` option, a message like the following lets yo
 
 ## Overriding default triplets
 
-As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is inconsistent with Linux and Mac OS where only static libraries are built.
+As you may have noticed, the default triplets for Windows (`x86-windows` and `x64-windows`) install dynamic libraries, while a suffix (`-static`) is needed for static libraries. This is different with Linux and Mac OS where static libraries are built by `x64-linux` and `x64-osx`.
 
 Using `--overlay-ports` it is possible to override the default triplets to accomplish the same behavior on Linux:
 
 * `x64-linux`: Builds dynamic libraries,
 * `x64-linux-static`: Builds static libraries.
 
-### Step 1: Create the overriden triplet
-
-Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`.
-
-```
-~/vcpkg$ mv ../custom-triplets/x64-linux-dynamic.cmake ../custom-triplets/x64-linux.cmake
-```
+### Step 1: Create the overlay triplets
 
-### Step 2: Copy and rename the default triplet
+Using the custom triplet created in the previous example, rename `custom-triplets/x64-linux-dynamic.cmake` to `custom-triplets/x64-linux.cmake`. Then, copy the default `x64-linux` triplet (which builds static libraries) in your `custom-triplets` folder and rename it to `x64-linux-static.cmake`.
 
-Then, copy the default `x64-linux` triplet (which builds static libraries) in your `/custom-triplets` folder and rename it to `x64-linux-static.cmake`.
-
-```
-~/vcpkg$ cp ./triplets/x64-linux.cmake ../custom-triplets/x64-linux-static.cmake
+```sh
+~/git$ mv custom-triplets/x64-linux-dynamic.cmake custom-triplets/x64-linux.cmake
+~/git$ cp vcpkg/triplets/x64-linux.cmake custom-triplets/x64-linux-static.cmake
 ```
 
-### Step 3: Use `--overlay-ports` to override default triplets
+### Step 2: Use `--overlay-ports` to override default triplets
 
 Use the `--overlay-triplets` option to include the triplets in the `custom-triplets` directory.
 
 ```
-./vcpkg install sqlite3:x64-linux --overlay-triplets=../custom-triplets
+~/git$ vcpkg/vcpkg install sqlite3:x64-linux --overlay-triplets=custom-triplets
 The following packages will be built and installed:
     sqlite3[core]:x64-linux
 Starting package 1/1: sqlite3:x64-linux
 Building package sqlite3[core]:x64-linux...
--- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake
 -- Downloading https://sqlite.org/2019/sqlite-amalgamation-3280000.zip...
 -- Extracting source /home/victor/git/vcpkg/downloads/sqlite-amalgamation-3280000.zip
 -- Applying patch fix-arm-uwp.patch
@@ -154,5 +122,5 @@ The package sqlite3:x64-linux provides CMake targets:
 Note that the default triplet is masked by your custom triplet:
 
 ```
--- Loading triplet configuration from: /home/custom-triplets/x64-linux.cmake
+-- Loading triplet configuration from: /home/victor/git/custom-triplets/x64-linux.cmake
 ```
diff --git a/docs/index.md b/docs/index.md
index 5d83b5804..b2f0a53b2 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -21,6 +21,11 @@ Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This too
 - [Portfile functions](maintainers/portfile-functions.md)
 - [Maintainer Guidelines](maintainers/maintainer-guide.md)
 
+### Tool Maintainer Help
+
+- [Testing](tool-maintainers/testing.md)
+- [Maintainer Guidelines](maintainers/maintainer-guide.md)
+
 ### Specifications
 
 - [Export](specifications/export-command.md)
diff --git a/docs/tool-maintainers/testing.md b/docs/tool-maintainers/testing.md
new file mode 100644
index 000000000..28cc9e099
--- /dev/null
+++ b/docs/tool-maintainers/testing.md
@@ -0,0 +1,162 @@
+Testing
+=======
+
+Testing vcpkg is important whenever one makes changes to the tool itself, and
+writing new tests and keeping them up to date is also very important. If one's
+code is subtly broken, we'd rather find it out right away than a few weeks down
+the line when someone complains!
+
+Running Tests
+-------------
+
+Before anything else, we should know whether you can actually run the tests!
+All you should need is a way to build vcpkg -- anything will do! All you have to
+do is follow the guide 😄
+
+With `$VCPKG_DIRECTORY` being the directory where you have cloned vcpkg, create
+a build directory in `$VCPKG_DIRECTORY/toolsrc` (commonly named `out`), and
+`cd` into it. Make sure to clean it out if it already exists!
+
+```sh
+$ cmake .. -DCMAKE_BUILD_TYPE=Debug -G Ninja
+$ cmake --build .
+$ ./vcpkg-test # ./vcpkg-test [$SPECIFIC_TEST] for a specific set of tests
+$ # i.e., ./vcpkg-test [arguments]
+```
+
+If you make any modifications to `vcpkg`, you'll have to do the
+`cmake --build .` step again.
+
+Writing Tests
+-------------
+
+In your journey to write new tests, and to modify existing tests, reading the
+[Catch2 documentation] will be very helpful! Come back after reading those 😀
+
+You'll want to place your tests in one of the existing files, or, if it doesn't
+belong in any of those, in a [new file](#adding-new-test-files).
+
+The layout of these tests is as follows:
+
+```cpp
+// ... includes
+
+TEST_CASE("Name of test", "[filename without the .cpp]") {
+  // setup and the like
+  REQUIRE(some boolean expression);
+}
+
+// etc.
+```
+
+You want to give these test cases good, descriptive, unique names, like
+`SourceParagraph construct minimum` -- it doesn't need to be extremely clear
+english, and shorthand is good, but make sure it's clear what the test is from
+the name. For the latter parameter, known as "tags", you should at least put the
+name of the file which the test case is in -- e.g., in `arguments.cpp`, you'd
+tag all of the test cases with `[arguments]`.
+
+If you wish to add helper functions, make sure to place them in an anonymous
+namespace -- this will ensure that they don't trample over anybody else's
+space. Additionally, there are a few helper functions that live in
+`<vcpkg-test/util.h>` and `src/vcpkg-test/util.cpp` -- make sure to look into
+them so that you're not rewriting functionality.
+
+That should be all you need to know to start writing your own tests!
+Remember to check out the [Catch2 documentation]
+if you'd like to get more advanced with your tests,
+and good luck on your testing journey!
+
+Adding New Test Files
+---------------------
+
+Adding new test files should be easy and straightforward. All it requires is
+creating a new source file in `toolsrc/src/vcpkg-test`, and then rerunning
+`CMake` in order to pick up the glob changes.
+
+### Example
+
+Let's try writing a new test file called `example` (very creative, I know).
+
+First, we should create a file, `example.cpp`, in `toolsrc/src/vcpkg-test`:
+
+```cpp
+// vcpkg-test/example.cpp
+#include <vcpkg-test/catch.h>
+```
+
+This is the minimum file needed for tests; let's rebuild our CMake directory.
+You'll have to clean out the existing `out` directory for CMake to rerun
+globbing.
+
+```sh
+$ cmake .. -DCMAKE_BUILD_TYPE=Debug -G Ninja
+# ...
+-- Build files have been written to: $VCPKG_DIRECTORY/toolsrc/out
+$ cmake --build .
+[80/80] Linking CXX executable vcpkg.exe
+```
+
+Okay, now let's make sure this worked; add a test case to `example.cpp`:
+
+```cpp
+TEST_CASE("Example 1 - fail", "[example]") {
+  REQUIRE(false);
+}
+```
+
+Now build the tests again, and run them:
+
+```sh
+$ cmake --build .
+[2/2] Linking CXX executable vcpkg-test.exe
+$ ./vcpkg-test
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+vcpkg-test.exe is a Catch v2.9.1 host application.
+Run with -? for options
+
+-------------------------------------------------------------------------------
+Example 1 - fail
+-------------------------------------------------------------------------------
+$VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(3)
+...............................................................................
+
+$VCPKG_DIRECTORY/toolsrc/src/vcpkg-test/example.cpp(14): FAILED:
+  REQUIRE( false )
+
+===============================================================================
+test cases:  102 |  101 passed | 1 failed
+assertions: 3611 | 3610 passed | 1 failed
+```
+
+Hopefully, that worked! It should compile correctly, and have one failing test.
+Now let's try a more complex test, after deleting the old one;
+
+```cpp
+// add #include <vcpkg/base/strings.h> to the top of the file
+namespace Strings = vcpkg::Strings;
+
+TEST_CASE("Example 2 - success", "[example]") {
+  std::string hello = "Hello";
+  REQUIRE(Strings::case_insensitive_ascii_equals(hello, "hELLo"));
+  REQUIRE_FALSE(Strings::case_insensitive_ascii_starts_with(hello, "E"));
+}
+```
+
+Now compile and build the tests, and this time let's only run our example tests:
+
+```sh
+$ cmake --build .
+[2/2] Linking CXX executable vcpkg-test.exe
+$ ./vcpkg-test [example]
+Filters: [example]
+===============================================================================
+All tests passed (2 assertions in 1 test case)
+```
+
+Hopefully you have one test running and succeeding! If you have that, you have
+succeeded at adding a new file to vcpkg's tests. Congratulations! Have fun on
+the rest of your journey 🐱‍👤😁
+
+[Catch2 documentation]: https://github.com/catchorg/Catch2/blob/master/docs/tutorial.md#top