Auto merge of #5350 - feministy:docs-reorg, r=indirect

[docs] consolidate all docs into sub folder

👋 goodness, that was a lot of typing! this is the first step of many for #5026.

the only section that isn't complete with these changes is `RELEASING.md`, which is in progress in #5252 (those changes will be moved into the proper location if this PR goes in first).

i made a few minor tweaks to the project's README to support this organization. i also left the code of conduct in the root.

~~one thing i *am concerned about* is that our little "guidelines for contributing" warning message on PRs is going to disappear after this gets merged because `CONTRIBUTING.md` is no longer in the root~~

~~should i put a file in the root called `CONTRIBUTING.md` that links to the docs for contributing? 🤔  i'm not 100% sure on how the github integration for that works so y'all let me know.~~

19 files changed, 466 insertions, 251 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8349280d..8dc0548a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,36 +1,17 @@
-# Contributing
+# Contributing to Bundler
 
-Bundler welcomes contributions from *everyone*. While contributing, please follow the project [code of conduct](http://bundler.io/conduct.html), so that everyone can be included.
-
-If you'd like to help make Bundler better, you totally rock! Here are some ways you can contribute:
-
-  - by using prerelease versions (run `gem install bundler --pre`)
-  - by [reporting bugs you encounter or suggesting new features](https://github.com/bundler/bundler/issues/new)
-  - by adding to or editing [the Bundler documentation website](http://bundler.io) and [Bundler man pages](http://bundler.io/man/bundle.1.html)
-  - by [checking issues for completeness](https://github.com/bundler/bundler/blob/master/DEVELOPMENT.md#bug-triage)
-  - by closing issues that are not complete
-  - by adding a failing test for reproducible [reported bugs](https://github.com/bundler/bundler/issues)
-  - by reviewing [pull requests](https://github.com/bundler/bundler/pulls) and suggesting improvements
-  - by improving existing code, including suggestions from [PullReview](https://www.pullreview.com/github/bundler/bundler/reviews/master) or [CodeClimate](https://codeclimate.com/github/bundler/bundler)
-  - by [writing code](https://github.com/bundler/bundler/blob/master/DEVELOPMENT.md) (no patch is too small! fix typos or bad whitespace)
-  - by backfilling [unit tests](https://github.com/bundler/bundler/tree/master/spec/bundler) for modules that lack [coverage](https://codeclimate.com/github/bundler/bundler/coverage)
-
-If you need help getting started, check out the [DEVELOPMENT.md](https://github.com/bundler/bundler/blob/master/DEVELOPMENT.md) file for steps that will get you up and running.
+Welcome to Bundler! We are so happy that you're here. We know it can be daunting to joining a new open source project, so here's a quick overview of what you can expect from this documentation.
 
-Thanks for helping us make Bundler better.
-
-# Roadmap
-
-If you're interested in reading some of the potential ideas or plans for Bundler, see the official Bundler [Trello Board](https://trello.com/b/DioUaKgx/bundler).
-
-# Troubleshooting
+Bundler welcomes contributions from *everyone*. While contributing, please follow the project [code of conduct](http://bundler.io/conduct.html), so that everyone can be included.
 
-If you're having a problem, please see [ISSUES](https://github.com/bundler/bundler/blob/master/ISSUES.md) for troubleshooting steps and a guide for how to submit a ticket that will help us solve the problem you are having as quickly as possible.
+## Quick start
 
-# Requesting Features
+Some guides you might find useful:
 
-Feel free to discuss your ideas or feature requests on any of the lists or channels listed below or [create an issue](https://github.com/bundler/bundler/issues/new) with the `feature-request` label. Feature-wise, we consider Bundler stable, so the core team does not tend to work on feature suggestions. Pull requests are welcome though!
+* [Submitting pull requests](doc/development/PULL_REQUESTS.md)
+* [Filing an issue](doc/contributing/ISSUES.md)
+* [Bug triage](doc/contributing/BUG_TRIAGE.md)
 
-# Discussing Bundler
+## Comprehensive guides
 
-If you'd like to discuss features, ask questions, or just engage in general Bundler-focused discussion, please see the [#bundler](irc://irc.freenode.net/#bundler) IRC channel on Freenode, and the [Bundler mailing list](http://groups.google.com/group/ruby-bundler) on Google Groups.
+Not finding what you're looking for? More comprehensive guides are [available here](doc/README.md).
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
deleted file mode 100644
index 97e764de..00000000
--- a/DEVELOPMENT.md
+++ /dev/null
@@ -1,150 +0,0 @@
-Great to have you here! Here are a few ways you can help out with [Bundler](http://github.com/bundler/bundler).
-
-# Where should I start?
-
-You can start learning about Bundler by reading [the documentation](http://bundler.io). If you want, you can also read a (lengthy) explanation of [why Bundler exists and what it does](http://bundler.io/rationale.html). You can also check out discussions about Bundler on the [Bundler mailing list](https://groups.google.com/group/ruby-bundler) and in the [Bundler IRC channel](http://webchat.freenode.net/?channels=%23bundler), which is #bundler on Freenode. Please note that this project is released with a contributor [code of conduct](http://bundler.io/conduct.html). By participating in this project you agree to abide by its terms.
-
-## Your first commits
-
-If you’re interested in contributing to Bundler, that’s awesome! We’d love your help.
-
-If you have any questions after reading this page, please feel free to contact either [@indirect](https://github.com/indirect), [@segiddins](https://github.com/segiddins), or [@RochesterinNYC](https://github.com/RochesterinNYC). They are all happy to provide help working through your first bug fix or thinking through the problem you’re trying to resolve.
-
-## How you can help
-
-We track [small bugs and features](https://github.com/bundler/bundler/labels/contribution%3A%20small) so that anyone who wants to help can start with something that's not too overwhelming. We also keep a [list of things anyone can help with, any time](https://github.com/bundler/bundler/blob/master/CONTRIBUTING.md#contributing). If nothing on those lists looks good, talk to us, and we'll figure out what you can help with. We can absolutely use your help, no matter what level of programming skill you have at the moment.
-
-# Development setup
-
-Bundler doesn't use a Gemfile to list development dependencies, because when we tried it we couldn't tell if we were awake or it was just another level of dreams. To work on Bundler, you'll probably want to do a couple of things.
-
-  1. Install `groff-base` and `graphviz` packages using your package manager, e.g for ubuntu
-
-        $ sudo apt-get install graphviz groff-base -y
-
-     and for OS X (with brew installed)
-
-        $ brew install graphviz homebrew/dupes/groff
-
-  2. Install Bundler's development dependencies
-
-        $ bin/rake spec:deps
-
-  3. Run the test suite, to make sure things are working
-
-        $ bin/rake spec
-
-  4. Set up a shell alias to run Bundler from your clone, e.g. a Bash alias:
-
-        $ alias dbundle='BUNDLE_TRAMPOLINE_DISABLE=1 ruby -I /path/to/bundler/lib /path/to/bundler/exe/bundle'
-
-     The `BUNDLE_TRAMPOLINE_DISABLE` environment variable ensures that the version of Bundler in `/path/to/bundler/lib` will be used. Without that environment setting, Bundler will automatically download, install, and run the version of Bundler listed in `Gemfile.lock`. With that set up, you can test changes you've made to Bundler by running `dbundle`, without interfering with the regular `bundle` command.
-
-To dive into the code with Pry: `RUBYOPT=-rpry dbundle` to require pry and then run commands.
-
-# Submitting Pull Requests
-
-Before you submit a pull request, please remember to do the following:
-
-- Make sure the code formatting and styling adheres to the guidelines. We use Rubocop for this. Lack of formatting adherence will result in automatic Travis build failures.
-
-        $ bin/rubocop -a
-
-- Please run the test suite:
-
-        $ bin/rspec
-
-- If you are unable to run the entire test suite, please run the unit test suite and at least the integration specs related to the command or domain of Bundler that your code changes relate to.
-
-- Ex. For a pull request that changes something with `bundle update`, you might run:
-
-        $ bin/rspec spec/bundler
-        $ bin/rspec spec/commands/update_spec.rb
-
-- Please ensure that the commit messages included in the pull request __do not__ have the following:
-  - `@tag` Github user or team references (ex. `@indirect` or `@bundler/core`)
-  - `#id` references to issues or pull requests (ex. `#43` or `bundler/bundler-site#12`)
-
-  If you want to use these mechanisms, please instead include them in the pull request description. This prevents multiple notifications or references being created on commit rebases or pull request/branch force pushes.
-
-- Additionally, do not use `[ci skip]` or `[skip ci]` mechanisms in your pull request titles/descriptions or commit messages. Every potential commit and pull request should run through Bundler's CI system. This applies to all changes/commits (ex. even a change to just documentation or the removal of a comment).
-
-# Bug triage
-
-Triage is the work of processing tickets that have been opened into actionable issues, feature requests, or bug reports. That includes verifying bugs, categorizing the ticket, and ensuring there's enough information to reproduce the bug for anyone who wants to try to fix it.
-
-We've created an [issues guide](https://github.com/bundler/bundler/blob/master/ISSUES.md) to walk Bundler users through the process of troubleshooting issues and reporting bugs.
-
-If you'd like to help, awesome! You can [report a new bug](https://github.com/bundler/bundler/issues/new) or browse our [existing open tickets](https://github.com/bundler/bundler/issues).
-
-Not every ticket will point to a bug in Bundler's code, but open tickets usually mean that there is something we could improve to help that user. Sometimes that means writing additional documentation, sometimes that means making error messages clearer, and sometimes that means explaining to a user that they need to install git to use git gems.
-
-When you're looking at a ticket, here are the main questions to ask:
-
-  * Can I reproduce this bug myself?
-  * Are the steps to reproduce clearly stated in the ticket?
-  * Which versions of Bundler (1.1.x, 1.2.x, git, etc.) manifest this bug?
-  * Which operating systems (OS X, Windows, Ubuntu, CentOS, etc.) manifest this bug?
-  * Which rubies (MRI, JRuby, Rubinius, etc.) and which versions (1.8.7, 1.9.3, etc.) have this bug?
-
-If you can't reproduce an issue, chances are good that the bug has been fixed (hurrah!). That's a good time to post to the ticket explaining what you did and how it worked.
-
-If you can reproduce an issue, you're well on your way to fixing it. :) Fixing issues is similar to adding new features:
-
-  1. Discuss the fix on the existing issue. Coordinating with everyone else saves duplicate work and serves as a great way to get suggestions and ideas if you need any.
-  2. Base your commits on the correct branch. Bugfixes for 1.x versions of Bundler should be based on the matching 1-x-stable branch.
-  3. Commit the code and at least one test covering your changes to a named branch in your fork.
-  4. Put a line in the [CHANGELOG](https://github.com/bundler/bundler/blob/master/CHANGELOG.md) summarizing your changes under the next release under the “Bugfixes” heading.
-  5. Send us a [pull request](https://help.github.com/articles/using-pull-requests) from your bugfix branch.
-
-Finally, the ticket may be a duplicate of another older ticket. If you notice a ticket is a duplicate, simply comment on the ticket noting the original ticket’s number. For example, you could say “This is a duplicate of issue #42, and can be closed”.
-
-
-# Adding New Features
-
-If you would like to add a new feature to Bundler, please follow these steps:
-
-  1. [Create an issue](https://github.com/bundler/bundler/issues/new) with the [`feature-request` label](https://github.com/bundler/bundler/labels/type:%20feature-request) to discuss your feature.
-  2. Base your commits on the master branch, since we follow [SemVer](http://semver.org) and don't add new features to old releases.
-  3. Commit the code and at least one test covering your changes to a feature branch in your fork.
-  4. Send us a [pull request](https://help.github.com/articles/using-pull-requests) from your feature branch.
-
-If you don't hear back immediately, don’t get discouraged! We all have day jobs, but we respond to most tickets within a day or two.
-
-
-# Beta testing
-
-Early releases require heavy testing, especially across various system setups. We :heart: testers, and are big fans of anyone who can run `gem install bundler --pre` and try out upcoming releases in their development and staging environments.
-
-There may not always be prereleases or beta versions of Bundler. The Bundler team will tweet from the [@bundlerio account](http://twitter.com/bundlerio) when a prerelease or beta version becomes available. You are also always welcome to try checking out master and building a gem yourself if you want to try out the latest changes.
-
-
-# Translations
-
-We don't currently have any translations, but please reach out to us if you would like to help get this going.
-
-
-# Documentation
-
-Code needs explanation, and sometimes those who know the code well have trouble explaining it to someone just getting into it. Because of that, we welcome documentation suggestions and patches from everyone, especially if they are brand new to using Bundler.
-
-Bundler has two main sources of documentation: the built-in help (including usage information and man pages) and the [Bundler documentation site](http://bundler.io).
-
-If you’d like to submit a patch to the man pages, follow the steps for submitting a pull request above. All of the man pages are located in the `man` directory. Just use the “Documentation” heading when you describe what you did in the changelog.
-
-If you have a suggestion or proposed change for [bundler.io](http://bundler.io), please open an issue or send a pull request to the [bundler-site](https://github.com/bundler/bundler-site) repository.
-
-
-# Community
-
-Community is an important part of all we do. If you’d like to be part of the Bundler community, you can jump right in and start helping make Bundler better for everyone who uses it.
-
-It would be tremendously helpful to have more people answering questions about Bundler (and often simply about [Rubygems](https://github.com/rubygems/rubygems) or Ruby itself) in our [issue tracker](https://github.com/bundler/bundler/issues) or on [Stack Overflow](http://stackoverflow.com/questions/tagged/bundler).
-
-Additional documentation and explanation is always helpful, too. If you have any suggestions for the Bundler website [bundler.io](http://bundler.io), we would absolutely love it if you opened an issue or pull request on the [bundler-site](https://github.com/bundler/bundler-site) repository.
-
-Finally, sharing your experiences and discoveries by writing them up is a valuable way to help others who have similar problems or experiences in the future. You can write a blog post, create an example and commit it to Github, take screenshots, or make videos.
-
-Publishing examples of how Bundler is used helps everyone, and we’ve discovered that people already use it in ways that we never imagined when we were writing it. If you’re still not sure what to write about, there are also several projects doing interesting things based on Bundler. They could probably use publicity too.
-
-Finally, all contributors to the Bundler project must agree to the contributor [code of conduct](http://bundler.io/conduct.html). By participating in this project you agree to abide by its terms.
diff --git a/README.md b/README.md
index 0c7e1e70..56ec5c5c 100644
--- a/README.md
+++ b/README.md
@@ -11,21 +11,28 @@ It does this by managing the gems that the application depends on. Given a list
 
 ### Installation and usage
 
+To install:
+
 ```
 gem install bundler
+```
+
+Bundler is most commonly used to manage your application's dependencies. To use it for this:
+
+```
 bundle init
 echo 'gem "rspec"' >> Gemfile
 bundle install
 bundle exec rspec
 ```
 
-For help with installation issues, see [ISSUES](https://github.com/bundler/bundler/blob/master/ISSUES.md)
-
 See [bundler.io](http://bundler.io) for the full documentation.
 
 ### Troubleshooting
 
-For help with common problems, see [ISSUES](https://github.com/bundler/bundler/blob/master/ISSUES.md).
+For help with common problems, see [TROUBLESHOOTING](doc/TROUBLESHOOTING.md).
+
+Still stuck? Try [filing an issue](doc/contributing/ISSUES.md).
 
 ### Supporting
 
@@ -34,13 +41,13 @@ Bundler is maintained by <a href="https://rubytogether.org/">Ruby Together</a>,
 
 ### Other questions
 
-To see what has changed in recent versions of Bundler, see the [CHANGELOG](https://github.com/bundler/bundler/blob/master/CHANGELOG.md).
+To see what has changed in recent versions of Bundler, see the [CHANGELOG](CHANGELOG.md).
 
-Feel free to chat with the Bundler core team (and many other users) on IRC in the  [#bundler](irc://irc.freenode.net/bundler) channel on Freenode, or via email on the [Bundler mailing list](http://groups.google.com/group/ruby-bundler).
+To get in touch with the Bundler core team and other Bundler users, please see [getting help](doc/contributing/GETTING_HELP.md).
 
 ### Contributing
 
-If you'd like to contribute to Bundler, that's awesome, and we <3 you. There's a guide to contributing to Bundler (both code and general help) over in [DEVELOPMENT](https://github.com/bundler/bundler/blob/master/DEVELOPMENT.md).
+If you'd like to contribute to Bundler, that's awesome, and we <3 you. There's a guide to contributing to Bundler (both code and general help) over in [our documentation section](doc/README.md).
 
 ### Code of Conduct
 
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 00000000..534dd941
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,30 @@
+# Docs: Contributing and developing Bundler
+
+_If you're looking for documentation on how to use Bundler: visit [bundler.io](http://bundler.io/), or run `bundle help` from the command line. You may also be interested in [troubleshooting common issues](TROUBLESHOOTING.md) found when using Bundler._
+
+Bundler welcomes contributions from *everyone*. While contributing, please follow the project [code of conduct](http://bundler.io/conduct.html), so that everyone can be included.
+
+If you'd like to help make Bundler better, you totally rock! Thanks for helping us make Bundler better.
+
+## Contributing
+
+* [Overview & getting started](contributing/README.md)
+* [How you can help: your first contributions!](contributing/HOW_YOU_CAN_HELP.md)
+* [Bug triage](contributing/BUG_TRIAGE.md)
+* [Getting help](contributing/GETTING_HELP.md)
+* [Filing issues](contributing/ISSUES.md)
+* [Community](contributing/COMMUNITY.md)
+
+## Development
+
+* [Overview](development/README.md)
+* [Development setup](development/SETUP.md)
+* [Submitting pull requests](development/PULL_REQUESTS.md)
+* [Adding new features](development/NEW_FEATURES.md)
+* [Releasing Bundler](development/RELEASING.md)
+
+## Documentation
+
+* [Overview](documentation/README.md)
+* [Writing docs for man pages](documentation/WRITING.md)
+* [Documentation vision](documentation/VISION.md)
diff --git a/doc/TROUBLESHOOTING.md b/doc/TROUBLESHOOTING.md
new file mode 100644
index 00000000..e9187c50
--- /dev/null
+++ b/doc/TROUBLESHOOTING.md
@@ -0,0 +1,64 @@
+# Troubleshooting common issues
+
+Stuck using Bundler? Browse these common issues before [filing a new issue](contributing/ISSUES.md).
+
+## Permission denied when installing bundler
+
+Certain operating systems such as MacOS and Ubuntu have versions of Ruby that require elevated privileges to install gems.
+
+    ERROR:  While executing gem ... (Gem::FilePermissionError)
+      You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory.
+
+There are multiple ways to solve this issue. You can install bundler with elevated privilges using `sudo` or `su`.
+
+    sudo gem install bundler
+
+If you cannot elevated your privileges or do not want to globally install Bundler, you can use the `--user-install` option.
+
+    gem install bundler --user-install
+
+This will install Bundler into your home directory. Note that you will need to append `~/.gem/ruby/<ruby version>/bin` to your `$PATH` variable to use `bundle`.
+
+## Heroku errors
+
+Please open a ticket with [Heroku](https://www.heroku.com) if you're having trouble deploying. They have a professional support team who can help you resolve Heroku issues far better than the Bundler team can. If the problem that you are having turns out to be a bug in Bundler itself, [Heroku support](https://www.heroku.com/support) can get the exact details to us.
+
+## Other problems
+
+First, figure out exactly what it is that you're trying to do (see [XY Problem](http://xyproblem.info/)). Then, go to the [Bundler documentation website](http://bundler.io) and see if we have instructions on how to do that.
+
+Second, check [the compatibility
+list](http://bundler.io/compatibility.html), and make sure that the version of Bundler that you are using works with the versions of Ruby and Rubygems that you are using. To see your versions:
+
+    # Bundler version
+    bundle -v
+
+    # Ruby version
+    ruby -v
+
+    # Rubygems version
+    gem -v
+
+If these instructions don't work, or you can't find any appropriate instructions, you can try these troubleshooting steps:
+
+    # Remove user-specific gems and git repos
+    rm -rf ~/.bundle/ ~/.gem/bundler/ ~/.gems/cache/bundler/
+
+    # Remove system-wide git repos and git checkouts
+    rm -rf $GEM_HOME/bundler/ $GEM_HOME/cache/bundler/
+
+    # Remove project-specific settings
+    rm -rf .bundle/
+
+    # Remove project-specific cached gems and repos
+    rm -rf vendor/cache/
+
+    # Remove the saved resolve of the Gemfile
+    rm -rf Gemfile.lock
+
+    # Uninstall the rubygems-bundler and open_gem gems
+    rvm gemset use global # if using rvm
+    gem uninstall rubygems-bundler open_gem
+
+    # Try to install one more time
+    bundle install
diff --git a/doc/contributing/BUG_TRIAGE.md b/doc/contributing/BUG_TRIAGE.md
new file mode 100644
index 00000000..a8e92383
--- /dev/null
+++ b/doc/contributing/BUG_TRIAGE.md
@@ -0,0 +1,38 @@
+# Bug triage
+
+Triage is the work of processing tickets that have been opened into actionable issues, feature requests, or bug reports. That includes verifying bugs, categorizing the ticket, and ensuring there's enough information to reproduce the bug for anyone who wants to try to fix it.
+
+We've created an [issues guide](ISSUES.md) to walk Bundler users through the process of troubleshooting issues and reporting bugs.
+
+If you'd like to help, awesome! You can [report a new bug](https://github.com/bundler/bundler/issues/new) or browse our [existing open tickets](https://github.com/bundler/bundler/issues).
+
+Not every ticket will point to a bug in Bundler's code, but open tickets usually mean that there is something we could improve to help that user. Sometimes that means writing additional documentation, sometimes that means making error messages clearer, and sometimes that means explaining to a user that they need to install git to use git gems.
+
+## Triaging existing issues
+
+When you're looking at a ticket, here are the main questions to ask:
+
+  * Can I reproduce this bug myself?
+  * Are the steps to reproduce clearly stated in the ticket?
+  * Which versions of Bundler (1.1.x, 1.2.x, git, etc.) manifest this bug?
+  * Which operating systems (OS X, Windows, Ubuntu, CentOS, etc.) manifest this bug?
+  * Which rubies (MRI, JRuby, Rubinius, etc.) and which versions (1.8.7, 1.9.3, etc.) have this bug?
+
+If you can't reproduce an issue, chances are good that the bug has been fixed (hurrah!). That's a good time to post to the ticket explaining what you did and how it worked.
+
+If you can reproduce an issue, you're well on your way to fixing it. :)
+
+## Fixing your triaged bug
+
+Fixing issues is similar to [adding new features](../development/NEW_FEATURES.md)!
+
+  1. Discuss the fix on the existing issue. Coordinating with everyone else saves duplicate work and serves as a great way to get suggestions and ideas if you need any.
+  2. Base your commits on the correct branch. Bugfixes for 1.x versions of Bundler should be based on the matching 1-x-stable branch.
+  3. Commit the code and at least one test covering your changes to a named branch in your fork.
+  4. Put a line in the [CHANGELOG](../../CHANGELOG.md) summarizing your changes under the next release under the “Bugfixes” heading.
+  5. Send us a [pull request](https://help.github.com/articles/using-pull-requests) from your bugfix branch.
+
+
+## Duplicates!
+
+Finally, the ticket may be a duplicate of another older ticket. If you notice a ticket is a duplicate, simply comment on the ticket noting the original ticket’s number. For example, you could say “This is a duplicate of issue #42, and can be closed”.
diff --git a/doc/contributing/COMMUNITY.md b/doc/contributing/COMMUNITY.md
new file mode 100644
index 00000000..c25ef63e
--- /dev/null
+++ b/doc/contributing/COMMUNITY.md
@@ -0,0 +1,13 @@
+# Community
+
+Community is an important part of all we do. If you’d like to be part of the Bundler community, you can jump right in and start helping make Bundler better for everyone who uses it.
+
+It would be tremendously helpful to have more people answering questions about Bundler (and often simply about [Rubygems](https://github.com/rubygems/rubygems) or Ruby itself) in our [issue tracker](https://github.com/bundler/bundler/issues) or on [Stack Overflow](http://stackoverflow.com/questions/tagged/bundler).
+
+Additional documentation and explanation is always helpful, too. If you have any suggestions for the Bundler website [bundler.io](http://bundler.io), we would absolutely love it if you opened an issue or pull request on the [bundler-site](https://github.com/bundler/bundler-site) repository.
+
+Sharing your experiences and discoveries by writing them up is a valuable way to help others who have similar problems or experiences in the future. You can write a blog post, create an example and commit it to Github, take screenshots, or make videos.
+
+Publishing examples of how Bundler is used helps everyone, and we’ve discovered that people already use it in ways that we never imagined when we were writing it. If you’re still not sure what to write about, there are also several projects doing interesting things based on Bundler. They could probably use publicity too.
+
+Finally, all contributors to the Bundler project must agree to the contributor [code of conduct](http://bundler.io/conduct.html). By participating in this project you agree to abide by its terms.
diff --git a/doc/contributing/GETTING_HELP.md b/doc/contributing/GETTING_HELP.md
new file mode 100644
index 00000000..55ccb5f5
--- /dev/null
+++ b/doc/contributing/GETTING_HELP.md
@@ -0,0 +1,11 @@
+# Getting help
+
+If you have any questions after reading the documentation for contributing, please feel free to contact either [@indirect](https://github.com/indirect), [@segiddins](https://github.com/segiddins), or [@RochesterinNYC](https://github.com/RochesterinNYC). They are all happy to provide help working through your first bug fix or thinking through the problem you’re trying to resolve.
+
+The best ways to get in touch are:
+
+* [Bundler Slack](https://bundler.slack.com).
+  * Not a member of the Slack? Join the Bundler team slack [here](http://slack.bundler.io/)!
+* [Bundler mailing list](http://groups.google.com/group/ruby-bundler)
+
+You may also find our guide on [filing issues](ISSUES.md) to be helpful as well!
diff --git a/doc/contributing/HOW_YOU_CAN_HELP.md b/doc/contributing/HOW_YOU_CAN_HELP.md
new file mode 100644
index 00000000..b1e90de5
--- /dev/null
+++ b/doc/contributing/HOW_YOU_CAN_HELP.md
@@ -0,0 +1,27 @@
+# How you can help: your first commits!
+
+If you’re interested in contributing to Bundler, that’s awesome! We’d love your help.
+
+If at any point you get stuck, here's how to [get in touch with the Bundler team for help](GETTING_HELP.md).
+
+## First contribution suggestions
+
+We track [small bugs and features](https://github.com/bundler/bundler/labels/contribution%3A%20small) so that anyone who wants to help can start with something that's not too overwhelming.
+
+Generally, great ways to get started helping out with Bundler are:
+
+  - using prerelease versions (run `gem install bundler --pre`)
+  - [reporting bugs you encounter or suggesting new features](https://github.com/bundler/bundler/issues/new)
+    - see our [issues guide](ISSUES.md) for help on filing issues
+    - see the [new features documentation](../development/NEW_FEATURES.md) for more
+  - adding to or editing [the Bundler documentation website](http://bundler.io) and [Bundler man pages](http://bundler.io/man/bundle.1.html)
+  - [checking issues for completeness](BUG_TRIAGE.md)
+  - closing issues that are not complete
+  - adding a failing test for reproducible [reported bugs](https://github.com/bundler/bundler/issues)
+  - reviewing [pull requests](https://github.com/bundler/bundler/pulls) and suggesting improvements
+  - improving existing code, including suggestions from [PullReview](https://www.pullreview.com/github/bundler/bundler/reviews/master) or [CodeClimate](https://codeclimate.com/github/bundler/bundler)
+  - writing code (no patch is too small! fix typos or bad whitespace)
+    - get started setting up your dev environment with [these instructions](../development/DEVELOPMENT_SETUP.md)
+  - backfilling [unit tests](https://github.com/bundler/bundler/tree/master/spec/bundler) for modules that lack [coverage](https://codeclimate.com/github/bundler/bundler/coverage)
+
+If nothing on those lists looks good, [talk to us](http://slack.bundler.io/), and we'll figure out what you can help with. We can absolutely use your help, no matter what level of programming skill you have at the moment.
diff --git a/ISSUES.md b/doc/contributing/ISSUES.md
index b7d18ea3..23a12330 100644
--- a/ISSUES.md
+++ b/doc/contributing/ISSUES.md
@@ -1,80 +1,20 @@
-# Bundler Issues
+# Filing Issues: a guide
 
 So! You're having problems with Bundler. This file is here to help. If you're running into an error, try reading the rest of this file for help. If you can't figure out how to solve your problem, there are also instructions on how to report a bug.
 
+Before filing an issue, check our [troubleshooting guide](../TROUBLESHOOTING.md) for quick fixes to common issues.
+
 ## Documentation
 
 Instructions for common Bundler uses can be found on the [Bundler documentation site](http://bundler.io/).
 
 Detailed information about each Bundler command, including help with common problems, can be found in the [Bundler man pages](http://bundler.io/man/bundle.1.html) or [Bundler Command Line Reference](http://bundler.io/v1.11/commands.html).
 
-## Troubleshooting
-
-### Permission denied when installing bundler
-
-Certain operating systems such as MacOS and Ubuntu have versions of Ruby that require evelated privileges to install gems.
-
-    ERROR:  While executing gem ... (Gem::FilePermissionError)
-      You don't have write permissions for the /Library/Ruby/Gems/2.0.0 directory.
-
-There are multiple ways to solve this issue. You can install bundler with elevated privilges using `sudo` or `su`.
-
-    sudo gem install bundler
-
-If you cannot elevated your privileges or do not want to globally install Bundler, you can use the `--user-install` option.
-
-    gem install bundler --user-install
-
-This will install Bundler into your home directory. Note that you will need to append `~/.gem/ruby/<ruby version>/bin` to your `$PATH` variable to use `bundle`.
-
-### Heroku errors
-
-Please open a ticket with [Heroku](https://www.heroku.com) if you're having trouble deploying. They have a professional support team who can help you resolve Heroku issues far better than the Bundler team can. If the problem that you are having turns out to be a bug in Bundler itself, [Heroku support](https://www.heroku.com/support) can get the exact details to us.
-
-### Other problems
-
-First, figure out exactly what it is that you're trying to do (see [XY Problem](http://xyproblem.info/)). Then, go to the [Bundler documentation website](http://bundler.io) and see if we have instructions on how to do that.
-
-Second, check [the compatibility
-list](http://bundler.io/compatibility.html), and make sure that the version of Bundler that you are
-using works with the versions of Ruby and Rubygems that you are using. To see your versions:
-
-    # Bundler version
-    bundle -v
-
-    # Ruby version
-    ruby -v
-
-    # Rubygems version
-    gem -v
-
-If these instructions don't work, or you can't find any appropriate instructions, you can try these troubleshooting steps:
-
-    # Remove user-specific gems and git repos
-    rm -rf ~/.bundle/ ~/.gem/bundler/ ~/.gems/cache/bundler/
-
-    # Remove system-wide git repos and git checkouts
-    rm -rf $GEM_HOME/bundler/ $GEM_HOME/cache/bundler/
-
-    # Remove project-specific settings
-    rm -rf .bundle/
-
-    # Remove project-specific cached gems and repos
-    rm -rf vendor/cache/
-
-    # Remove the saved resolve of the Gemfile
-    rm -rf Gemfile.lock
-
-    # Uninstall the rubygems-bundler and open_gem gems
-    rvm gemset use global # if using rvm
-    gem uninstall rubygems-bundler open_gem
-
-    # Try to install one more time
-    bundle install
-
 ## Reporting unresolved problems
 
-Hopefully the troubleshooting steps above resolved your problem. If things still aren't working the way you expect them to, please let us know so that we can diagnose and hopefully fix the problem you're having.
+Check our [troubleshooting common issues guide](../TROUBLESHOOTING.md) and see if your issues is resolved using the steps provided.
+
+Hopefully the troubleshooting steps above resolved your problem! If things still aren't working the way you expect them to, please let us know so that we can diagnose and hopefully fix the problem you're having.
 
 **The best way to report a bug is by providing a reproduction script.** See these examples:
 
diff --git a/doc/contributing/README.md b/doc/contributing/README.md
new file mode 100644
index 00000000..29e6d9dd
--- /dev/null
+++ b/doc/contributing/README.md
@@ -0,0 +1,38 @@
+# Contributing to Bundler
+
+Welcome to Bundler! We are so happy that you're here. We know it can be daunting to joining a new open source project, so here's a quick overview of what you can expect from this documentation.
+
+*Something missing?* Send us a [pull request](../development/PULL_REQUESTS.md)!
+
+**Recommended first steps**
+
+- Join us in the Bundler slack! Generate an invite [here](http://slack.bundler.io/)
+- *If you're interested in helping with code:*
+  - Get a quick overview of our [development process](../development/README.md)
+  - [Setup your machine for development](../development/SETUP.md)
+  - Checkout [How you can help: your first contributions!](contributing/HOW_YOU_CAN_HELP.md) for a list of suggestions to get started
+- *If you're interested in helping with documentation:*
+  - Read up on [how documentation works for Bundler](../documentation/README.md)
+  - Learn about our [documentation vision](../documentation/VISION.md)
+
+You can start learning about Bundler by reading [the documentation](http://bundler.io). If you want, you can also read a (lengthy) explanation of [why Bundler exists and what it does](http://bundler.io/rationale.html).
+
+##[How you can help: your first contributions!](contributing/HOW_YOU_CAN_HELP.md)
+
+A detailed overview of how to get started contributing to Bundler, including a long list of suggestions for your first project.
+
+##[Bug triage](contributing/BUG_TRIAGE.md)
+
+Want to take a stab at processing issues? Start here.
+
+##[Getting help](contributing/GETTING_HELP.md)
+
+How to get in touch with folks who can help when you're stuck. Don't worry! This happens to all of us. We're really nice, we promise.
+
+##[Filing issues](contributing/ISSUES.md)
+
+We see a lot of issues in the Bundler repo! Use this guide to file informative, actionable issues.
+
+##[Community](contributing/COMMUNITY.md)
+
+Learn more about our goals for the Bundler community and the ways you can help us build better together.
diff --git a/doc/development/NEW_FEATURES.md b/doc/development/NEW_FEATURES.md
new file mode 100644
index 00000000..9688ef8a
--- /dev/null
+++ b/doc/development/NEW_FEATURES.md
@@ -0,0 +1,10 @@
+# Adding New Features
+
+If you would like to add a new feature to Bundler, please follow these steps:
+
+  1. [Create an issue](https://github.com/bundler/bundler/issues/new) with the [`feature-request` label](https://github.com/bundler/bundler/labels/type:%20feature-request) to discuss your feature.
+  2. Base your commits on the master branch, since we follow [SemVer](http://semver.org) and don't add new features to old releases.
+  3. Commit the code and at least one test covering your changes to a feature branch in your fork.
+  4. Send us a [pull request](PULL_REQUESTS.md) from your feature branch.
+
+If you don't hear back immediately, don’t get discouraged! We all have day jobs, but we respond to most tickets within a day or two.
diff --git a/doc/development/PULL_REQUESTS.md b/doc/development/PULL_REQUESTS.md
new file mode 100644
index 00000000..37129f8e
--- /dev/null
+++ b/doc/development/PULL_REQUESTS.md
@@ -0,0 +1,40 @@
+# Submitting Pull Requests
+
+Before you submit a pull request, please remember to do the following:
+
+1. Check your code format and style
+2. Run the test suite
+3. Use a meaningful commit message without tags
+
+## Code formatting
+
+Make sure the code formatting and styling adheres to the guidelines. We use Rubocop for this. Lack of formatting adherence will result in automatic Travis build failures.
+
+      $ bin/rubocop -a
+
+## Tests
+
+Prior to submitting your PR, please run the test suite:
+
+      $ bin/rspec
+
+If you are unable to run the entire test suite, please run the unit test suite and at least the integration specs related to the command or domain of Bundler that your code changes relate to.
+
+Ex. For a pull request that changes something with `bundle update`, you might run:
+
+      $ bin/rspec spec/bundler
+      $ bin/rspec spec/commands/update_spec.rb
+
+## Commit messages
+
+Please ensure that the commit messages included in the pull request __do not__ have the following:
+  - `@tag` Github user or team references (ex. `@indirect` or `@bundler/core`)
+  - `#id` references to issues or pull requests (ex. `#43` or `bundler/bundler-site#12`)
+
+If you want to use these mechanisms, please instead include them in the pull request description. This prevents multiple notifications or references being created on commit rebases or pull request/branch force pushes.
+
+Additionally, do not use `[ci skip]` or `[skip ci]` mechanisms in your pull request titles/descriptions or commit messages. Every potential commit and pull request should run through Bundler's CI system. This applies to all changes/commits (ex. even a change to just documentation or the removal of a comment).
+
+## CHANGELOG.md
+
+Don't forget to add your changes into the CHANGELOG! If you're submitting documentation, note the changes under the "Documentation" heading.
diff --git a/doc/development/README.md b/doc/development/README.md
new file mode 100644
index 00000000..3d100624
--- /dev/null
+++ b/doc/development/README.md
@@ -0,0 +1,19 @@
+# Development
+
+So, you're ready to start contributing to Bundler! You've come to the right place. Here you'll find an overview of how to work on Bundler locally and a description of the process from code to release.
+
+##[Development setup](development/SETUP.md)
+
+Guidelines for setting up your local development environment.
+
+##[Submitting pull requests](development/PULL_REQUESTS.md)
+
+An overview of our preferred PR process, including how to run the test suite and what to expect when you submit code for review.
+
+##[Adding new features](development/NEW_FEATURES.md)
+
+Guidelines for proposing and writing new features for Bundler.
+
+##[Releasing Bundler](development/RELEASING.md)
+
+A broad-strokes overview of the release process adhered to by the Bundler core team.
diff --git a/doc/development/RELEASING.md b/doc/development/RELEASING.md
new file mode 100644
index 00000000..eb496470
--- /dev/null
+++ b/doc/development/RELEASING.md
@@ -0,0 +1,9 @@
+# Releasing
+
+_Release process documentation is in progress, see [PR 5252](https://github.com/bundler/bundler/pull/5252)._
+
+## Beta testing
+
+Early releases require heavy testing, especially across various system setups. We :heart: testers, and are big fans of anyone who can run `gem install bundler --pre` and try out upcoming releases in their development and staging environments.
+
+There may not always be prereleases or beta versions of Bundler. The Bundler team will tweet from the [@bundlerio account](http://twitter.com/bundlerio) when a prerelease or beta version becomes available. You are also always welcome to try checking out master and building a gem yourself if you want to try out the latest changes.
diff --git a/doc/development/SETUP.md b/doc/development/SETUP.md
new file mode 100644
index 00000000..10f8dd30
--- /dev/null
+++ b/doc/development/SETUP.md
@@ -0,0 +1,29 @@
+# Development setup
+
+Bundler doesn't use a Gemfile to list development dependencies, because when we tried it we couldn't tell if we were awake or it was just another level of dreams. To work on Bundler, you'll probably want to do a couple of things.
+
+1. Install `groff-base` and `graphviz` packages using your package manager, e.g for ubuntu
+
+      $ sudo apt-get install graphviz groff-base -y
+
+   and for OS X (with brew installed)
+
+      $ brew install graphviz homebrew/dupes/groff
+
+2. Install Bundler's development dependencies
+
+      $ bin/rake spec:deps
+
+3. Run the test suite, to make sure things are working
+
+      $ bin/rake spec
+
+4. Set up a shell alias to run Bundler from your clone, e.g. a Bash alias:
+
+      $ alias dbundle='BUNDLE_TRAMPOLINE_DISABLE=1 ruby -I /path/to/bundler/lib /path/to/bundler/exe/bundle'
+
+   The `BUNDLE_TRAMPOLINE_DISABLE` environment variable ensures that the version of Bundler in `/path/to/bundler/lib` will be used. Without that environment setting, Bundler will automatically download, install, and run the version of Bundler listed in `Gemfile.lock`. With that set up, you can test changes you've made to Bundler by running `dbundle`, without interfering with the regular `bundle` command.
+
+## Debugging with `pry`
+
+To dive into the code with Pry: `RUBYOPT=-rpry dbundle` to require pry and then run commands.
diff --git a/doc/documentation/README.md b/doc/documentation/README.md
new file mode 100644
index 00000000..a29ff136
--- /dev/null
+++ b/doc/documentation/README.md
@@ -0,0 +1,29 @@
+# Documentation
+
+Code needs explanation, and sometimes those who know the code well have trouble explaining it to someone just getting into it. Because of that, we welcome documentation suggestions and patches from everyone, especially if they are brand new to using Bundler.
+
+Currently, Bundler has two main sources of documentation:
+
+1. built-in `help` (including usage information and man pages)
+2. [Bundler documentation site](http://bundler.io)
+
+If you have a suggestion or proposed change for [bundler.io](http://bundler.io), please open an issue or send a pull request to the [bundler-site](https://github.com/bundler/bundler-site) repository.
+
+Not sure where to write documentation? In general, follow these guidelines:
+
+* For an explanation of a specific Bundler command (ex: `bundle clean`): make changes to the man pages
+* For longer explanations or usage guides (ex: "Using Bundler with Rails"): create new documentation within the [bundler-site](https://github.com/bundler/bundler-site) repository
+
+If you are unsure where to begin, ping [@feministy](https://github.com/feministy) or [@indirect](https://github.com/indirect) in the Bundler Slack ([get an invite here](../contributing/GETTING_HELP.md)).
+
+## [Writing docs for man pages)](documentation/WRITING.md)
+
+If you’d like to submit a patch to the man pages, you're in the right place! Details on editing and previewing changes to man pages can be found here.
+
+## [Documentation vision](documentation/VISION.md)
+
+Just like Bundler, we have a grand plan (really, a wish list of sorts) for Bundler documentation. Preview our hopes and dreams for our documentation here.
+
+## Translations
+
+We don't currently have any translations, but please reach out to us if you would like to help get this going.
diff --git a/doc/documentation/VISION.md b/doc/documentation/VISION.md
new file mode 100644
index 00000000..3d660ee3
--- /dev/null
+++ b/doc/documentation/VISION.md
@@ -0,0 +1,26 @@
+# Documentation vision
+
+Currently, documentation for using Bundler is spread across two places:
+
+1. built-in `help` (including usage information and man pages)
+2. [Bundler documentation site](http://bundler.io)
+
+Additional documentation about using Bundler to publish gems can also be found on the [RubyGems guides](http://guides.rubygems.org/).
+
+## Goals
+
+Bundler documentation should provide users with assistance:
+
+1. Installing Bundler
+2. Using Bundler to manage an application's dependencies
+3. Using Bundler to create, package, and publish gems
+
+Our goal is to provide three types of documentation:
+
+* High level overviews that provide topical guidance
+* Step-by-step tutorials
+* Command-specific reference material for the CLI
+
+Additionally, this documentation should be readily available in a logical place and easy to follow.
+
+Someday, we'd like to create deep-dive reference material about the inner workings of Bundler. However, while this is part of our overall vision for Bundler documentation, it is not the focus of our current work.
diff --git a/doc/documentation/WRITING.md b/doc/documentation/WRITING.md
new file mode 100644
index 00000000..ce6dcce6
--- /dev/null
+++ b/doc/documentation/WRITING.md
@@ -0,0 +1,54 @@
+# Writing docs for man pages
+
+A primary source of help for Bundler users are the man pages: the output printed when you run `bundle help` (or `bundler help`). These pages can be a little tricky to format and preview, but are pretty straightforward once you get the hang of it.
+
+_Note: `bundler` and `bundle` may be used interchangeably in the CLI. This guide uses `bundle` because it's cuter._
+
+## What goes in man pages?
+
+We use man pages for Bundler commands used in the CLI (command line interface). They can vary in length from large (see `bundle install`) to very short (see `bundle clean`).
+
+To see a list of commands available in the Bundler CLI, type:
+
+      $ bundle help
+
+Our goal is to have a man page for every command.
+
+Don't see a man page for a command? Make a new page and send us a PR! We also welcome edits to existing pages.
+
+## Creating a new man page
+
+To create a new man page, simply create a new `.ronn` file in the `man/` directory.
+
+For example: to create a man page for the command `bundle cookies` (not a real command, sadly), I would create a file `man/bundle-cookies.ronn` and add my documentation there.
+
+## Formatting
+
+Our man pages use ronn formatting, a combination of Markdown and standard man page conventions. It can be a little weird getting used to it at first, especially if you've used Markdown a lot.
+
+[The ronn guide formatting guide](https://rtomayko.github.io/ronn/ronn.7.html) provides a good overview of the common types of formatting.
+
+In general, make your page look like the other pages: utilize sections like `##OPTIONS` and formatting like code blocks and definition lists where appropriate.
+
+If you're not sure if the formatting looks right, that's ok! Make a pull request with what you've got and we'll take a peek.
+
+## Previewing
+
+To preview your changes as they will print out for Bundler users, you'll need to run a series of commands:
+
+```
+$ rake spec:deps
+$ rake man:build
+$ man man/bundle-cookies.1
+```
+
+If you make more changes to `bundle-cookies.ronn`, you'll need to run the `rake man:build` again before previewing.
+
+## Testing
+
+We have tests for our documentation! The most important test file to run before you make your pull request is the one for the `help` command and another for documentation quality.
+
+```
+$ rspec ./spec/commands/help_spec.rb
+$ rspec ./spec/quality_spec.rb
+```