diff --git a/doc/05-repositories.md b/doc/05-repositories.md
index a675ab47c..b580d9b2a 100644
--- a/doc/05-repositories.md
+++ b/doc/05-repositories.md
@@ -161,6 +161,8 @@ VCS stands for version control system. This includes versioning systems like
 git, svn or hg. Composer has a repository type for installing packages from
 these systems.
 
+#### Maintaining a third party library fork
+
 There are a few use cases for this. The most common one is maintaining your
 own fork of a third party library. If you are using a certain library for your
 project and you decide to change something in the library, you will want your
@@ -188,6 +190,8 @@ Example assuming you patched monolog to fix a bug in the `bugfix` branch:
 When you run `php composer.phar update`, you should get your modified version
 of `monolog/monolog` instead of the one from packagist.
 
+#### Git alternatives
+
 Git is not the only version control system supported by the VCS repository.
 The following are supported:
 
diff --git a/doc/articles/troubleshooting.md b/doc/articles/troubleshooting.md
index fd83070bf..7efc1f064 100644
--- a/doc/articles/troubleshooting.md
+++ b/doc/articles/troubleshooting.md
@@ -1,7 +1,42 @@
 <!--
     tagline: Solving problems
 -->
-# Memory limit errors
+# Troubleshooting
+
+This is a list of common pitfalls on using Composer, and how to avoid them.
+
+## General
+
+1. When facing any kind of problems using Composer, be sure to **work with the
+   latest version**. See [self-update](03-cli.md#self-update) for details.
+
+2. Ensure you're **installing vendors straight from your `composer.json`** via
+
+~~~~
+    rm -rf vendor && composer update -v
+~~~~
+
+   when troubleshooting, excluding any possible interferences with existing
+   vendor installations or `composer.lock` entries.
+
+## Package not found
+
+1. Double-check you **don't have typos** in your `composer.json` or repository
+   branches and tag names.
+
+2. Be sure to **set the right
+   [minimum-stability](04-schema.md#minimum-stability)**. To get started or be
+   sure this is no issue, set `minimum-stability` to "dev".
+
+3. Packages **not coming from [Packagist](http://packagist.org/)** should
+   always be **defined in the root package** (the package depending on all
+   vendors).
+
+4. Use the **same vendor and package name** throughout all branches and tags of
+   your repository, especially when maintaining a third party fork and using
+   `replace`.
+
+## Memory limit errors
 
 If composer shows memory errors on some commands:
 
@@ -16,7 +51,8 @@ Get current value:
 
     php -r "echo ini_get('memory_limit').PHP_EOL;"
 
-Increase limit with `php.ini` for a `CLI SAPI` (ex. `/etc/php5/cli/php.ini` for Debian-like systems):
+Increase limit with `php.ini` for a `CLI SAPI` (ex. `/etc/php5/cli/php.ini` for
+Debian-like systems):
 
     ; Use -1 for unlimited or define explicit value like 512M
     memory_limit = -1
diff --git a/src/Composer/DependencyResolver/SolverProblemsException.php b/src/Composer/DependencyResolver/SolverProblemsException.php
index 4f4a25ab5..4b6df40ed 100644
--- a/src/Composer/DependencyResolver/SolverProblemsException.php
+++ b/src/Composer/DependencyResolver/SolverProblemsException.php
@@ -36,7 +36,7 @@ class SolverProblemsException extends \RuntimeException
         }
 
         if (strpos($text, 'could not be found') || strpos($text, 'no matching package found')) {
-            $text .= "\nPotential causes:\n - A typo in the package name\n - The package is not available in a stable-enough version according to your minimum-stability setting\n   see https://groups.google.com/d/topic/composer-dev/_g3ASeIFlrc/discussion for more details.\n";
+            $text .= "\nPotential causes:\n - A typo in the package name\n - The package is not available in a stable-enough version according to your minimum-stability setting\n   see <https://groups.google.com/d/topic/composer-dev/_g3ASeIFlrc/discussion> for more details.\n\nRead <http://getcomposer.org/doc/articles/troubleshooting.md> for further common problems.";
         }
 
         return $text;