diff --git a/.gitignore b/.gitignore
index 4b42e327d117851d5fb4283ef0ad607aed25096a..20b1a2dfd1417ba09e11bb27bdf5d8a50f86b577 100644
--- a/.gitignore
+++ b/.gitignore
@@ -33,30 +33,19 @@
 # Unignore our `brew` script.
 !/bin/brew
 
-# Ignore `share` contents (again).
-/share
-/share/doc
-/share/zsh
-/share/zsh/site-functions
-
 # Unignore our documentation.
 !/.github
-!/share/doc/homebrew
-!/share/man/man1/brew.1
-!/share/man/man1/brew-cask.1
-
-# Ignore `etc` contents (again)
-/etc
-/etc/bash_completion.d
+!/docs
+!/manpages
 
 # Unignore our shell completion
-!/etc/bash_completion.d/brew
-!/share/zsh/site-functions/_brew
+!/completions
 
 # Unignore our root-level metadata files.
 !/.gitignore
 !/.travis.yml
 !/.yardopts
 !/CODEOFCONDUCT.md
+!/CONTRIBUTING.md
 !/LICENSE.txt
 !/README.md
diff --git a/.github/CONTRIBUTING.md b/CONTRIBUTING.md
similarity index 89%
rename from .github/CONTRIBUTING.md
rename to CONTRIBUTING.md
index b9bd17f8973dba5d3aeed0973cdfad778c1198ae..0ebfc9b04ebc2952a351c80f4cb643b46eba7fd8 100644
--- a/.github/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -5,7 +5,7 @@ First time contributing to Homebrew? Read our [Code of Conduct](https://github.c
 
 * run `brew update` (twice)
 * run and read `brew doctor`
-* read [the Troubleshooting Checklist](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Troubleshooting.md#troubleshooting)
+* read [the Troubleshooting Checklist](https://github.com/Homebrew/brew/blob/master/docs/Troubleshooting.md#troubleshooting)
 * open an issue on the formula's repository
 
 ### Propose a feature
diff --git a/Library/Homebrew/README.md b/Library/Homebrew/README.md
index ccf0a02d79f331f4c7181f9087c76a25f9f7688a..b8bf5fd998f4964e9bdc03226c14cf8697009882 100644
--- a/Library/Homebrew/README.md
+++ b/Library/Homebrew/README.md
@@ -3,6 +3,6 @@ This is the (partially) documented public API for Homebrew.
 
 The main class you should look at is the {Formula} class (and classes linked from there). That's the class that's used to create Homebrew formulae (i.e. package descriptions). Assume anything else you stumble upon is private.
 
-You may also find the [Formula Cookbook](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Formula-Cookbook.md) and [Ruby Style Guide](https://github.com/styleguide/ruby) helpful in creating formulae.
+You may also find the [Formula Cookbook](https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md) and [Ruby Style Guide](https://github.com/styleguide/ruby) helpful in creating formulae.
 
 Good luck!
diff --git a/Library/Homebrew/cask/README.md b/Library/Homebrew/cask/README.md
index 1d0dc5882acfb610ff69e2d5ab34be3e69e036b5..0dc494af11ee86b3143ce78b446faee3a2723f3a 100644
--- a/Library/Homebrew/cask/README.md
+++ b/Library/Homebrew/cask/README.md
@@ -6,7 +6,7 @@ Homebrew-Cask extends [Homebrew](http://brew.sh) and brings its elegance, simpli
 
 We do this by providing a friendly Homebrew-style CLI workflow for the administration of macOS applications distributed as binaries.
 
-It鈥檚 implemented as a `homebrew` [external command](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/External-Commands.md) called `cask`.
+It鈥檚 implemented as a `homebrew` [external command](https://github.com/Homebrew/brew/blob/master/docs/External-Commands.md) called `cask`.
 
 [![Join the chat at https://gitter.im/caskroom/homebrew-cask](https://img.shields.io/badge/gitter-join%20chat-blue.svg)](https://gitter.im/caskroom/homebrew-cask)
 
diff --git a/Library/Homebrew/cmd/help.rb b/Library/Homebrew/cmd/help.rb
index 0bf3d0d8d93cae8c790428f4fde05dd4da64ee79..2a814b90bad397d8b5ab037788c008fd316de303 100644
--- a/Library/Homebrew/cmd/help.rb
+++ b/Library/Homebrew/cmd/help.rb
@@ -16,7 +16,7 @@ Troubleshooting:
 Developers:
   brew create [URL [--no-fetch]]
   brew edit [FORMULA...]
-  https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Formula-Cookbook.md
+  https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md
 
 Further help:
   man brew
diff --git a/Library/Homebrew/cmd/info.rb b/Library/Homebrew/cmd/info.rb
index 0310ab6240263f8237edd2341e5dea73ee842a44..2474aad573a68d087e4928e7bb71a5b9e5069168 100644
--- a/Library/Homebrew/cmd/info.rb
+++ b/Library/Homebrew/cmd/info.rb
@@ -14,7 +14,7 @@
 #:    information on all installed formulae.
 #:
 #:    See the docs for examples of using the JSON:
-#:    <https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md>
+#:    <https://github.com/Homebrew/brew/blob/master/docs/Querying-Brew.md>
 
 require "blacklist"
 require "caveats"
diff --git a/Library/Homebrew/cmd/list.rb b/Library/Homebrew/cmd/list.rb
index ba236068d1fb77f0b928f884f1001bbd59924a3d..4fdd8a85e67afd9d4b82a3cf96609406bde2ac92 100644
--- a/Library/Homebrew/cmd/list.rb
+++ b/Library/Homebrew/cmd/list.rb
@@ -64,6 +64,8 @@ module Homebrew
   UNBREWED_EXCLUDE_PATHS = %w[
     .github/*
     bin/brew
+    completions/zsh/_brew
+    docs/*
     lib/gdk-pixbuf-2.0/*
     lib/gio/*
     lib/node_modules/*
@@ -73,13 +75,11 @@ module Homebrew
     lib/ruby/gems/[12].*
     lib/ruby/site_ruby/[12].*
     lib/ruby/vendor_ruby/[12].*
+    manpages/brew.1
     share/pypy/*
     share/pypy3/*
-    share/doc/homebrew/*
     share/info/dir
-    share/man/man1/brew.1
     share/man/whatis
-    share/zsh/site-functions/_brew
   ].freeze
 
   def list_unbrewed
diff --git a/Library/Homebrew/cmd/tap-info.rb b/Library/Homebrew/cmd/tap-info.rb
index b599cb5915c8945adbbc60981b48ec378af57bcb..432d512873ae71e7e2a8f056ce2a4fef2ccad781 100644
--- a/Library/Homebrew/cmd/tap-info.rb
+++ b/Library/Homebrew/cmd/tap-info.rb
@@ -13,7 +13,7 @@
 #:    Pass `--installed` to get information on installed taps.
 #:
 #:    See the docs for examples of using the JSON:
-#:    <https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md>
+#:    <https://github.com/Homebrew/brew/blob/master/docs/Querying-Brew.md>
 
 require "tap"
 
diff --git a/Library/Homebrew/cmd/update-report.rb b/Library/Homebrew/cmd/update-report.rb
index b096dfc3b73d2763ef7ff6437720f8cbf56d33b9..1e9c8ccd3208c64165a593fa5155e0c3e7d2e3d7 100644
--- a/Library/Homebrew/cmd/update-report.rb
+++ b/Library/Homebrew/cmd/update-report.rb
@@ -294,15 +294,15 @@ module Homebrew
   end
 
   def link_completions_and_docs(repository = HOMEBREW_REPOSITORY)
-    return if HOMEBREW_PREFIX.to_s == repository.to_s
     command = "brew update"
-    link_src_dst_dirs(repository/"etc/bash_completion.d",
+    link_src_dst_dirs(repository/"completions/bash",
                       HOMEBREW_PREFIX/"etc/bash_completion.d", command)
-    link_src_dst_dirs(repository/"share/doc/homebrew",
+    link_src_dst_dirs(repository/"docs",
                       HOMEBREW_PREFIX/"share/doc/homebrew", command, link_dir: true)
-    link_src_dst_dirs(repository/"share/zsh/site-functions",
+    link_src_dst_dirs(repository/"completions/zsh",
                       HOMEBREW_PREFIX/"share/zsh/site-functions", command)
-    link_path_manpages(repository/"share", command)
+    link_src_dst_dirs(repository/"manpages",
+                      HOMEBREW_PREFIX/"share/man/man1", command)
   rescue => e
     ofail <<-EOS.undent
       Failed to link all completions, docs and manpages:
diff --git a/Library/Homebrew/dev-cmd/create.rb b/Library/Homebrew/dev-cmd/create.rb
index 1667fdfc7ca0699b6e34afa678ed9da37db7580a..19fd251b701c2775fa9331c96354f66daf1029b1 100644
--- a/Library/Homebrew/dev-cmd/create.rb
+++ b/Library/Homebrew/dev-cmd/create.rb
@@ -154,7 +154,7 @@ class FormulaCreator
   end
 
   def template; <<-EOS.undent
-    # Documentation: https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Formula-Cookbook.md
+    # Documentation: https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md
     #                http://www.rubydoc.info/github/Homebrew/brew/master/Formula
     # PLEASE REMOVE ALL GENERATED COMMENTS BEFORE SUBMITTING YOUR PULL REQUEST!
 
diff --git a/Library/Homebrew/dev-cmd/man.rb b/Library/Homebrew/dev-cmd/man.rb
index f90aa6d2a95e2a8170e0480534f2cc0252405c58..0627241a3d58bf543eb00c25074194ebbce7c0a3 100644
--- a/Library/Homebrew/dev-cmd/man.rb
+++ b/Library/Homebrew/dev-cmd/man.rb
@@ -7,8 +7,8 @@ require "ostruct"
 
 module Homebrew
   SOURCE_PATH = HOMEBREW_LIBRARY_PATH/"manpages"
-  TARGET_MAN_PATH = HOMEBREW_REPOSITORY/"share/man/man1"
-  TARGET_DOC_PATH = HOMEBREW_REPOSITORY/"share/doc/homebrew"
+  TARGET_MAN_PATH = HOMEBREW_REPOSITORY/"manpages"
+  TARGET_DOC_PATH = HOMEBREW_REPOSITORY/"docs"
 
   def man
     raise UsageError unless ARGV.named.empty?
diff --git a/Library/Homebrew/dev-cmd/tap-readme.rb b/Library/Homebrew/dev-cmd/tap-readme.rb
index f88d433894acd15e1b63bc8abefc8ac2e628f01f..e1a3e0eb4667b95ad487a9379660e2ba04e4430e 100644
--- a/Library/Homebrew/dev-cmd/tap-readme.rb
+++ b/Library/Homebrew/dev-cmd/tap-readme.rb
@@ -24,7 +24,7 @@ module Homebrew
     ```
 
     ## Documentation
-    `brew help`, `man brew` or check [Homebrew's documentation](https://github.com/Homebrew/brew/tree/master/share/doc/homebrew#readme).
+    `brew help`, `man brew` or check [Homebrew's documentation](https://github.com/Homebrew/brew/tree/master/docs#readme).
     EOS
 
     puts template if ARGV.verbose?
diff --git a/Library/Homebrew/formula.rb b/Library/Homebrew/formula.rb
index 4a48a5749a183a9cd958021cf5e9426da1f3f2d1..4cff28d8e4da97f860fa51f1319fa2437551a1d8 100644
--- a/Library/Homebrew/formula.rb
+++ b/Library/Homebrew/formula.rb
@@ -26,7 +26,7 @@ require "migrator"
 # @see SharedEnvExtension
 # @see FileUtils
 # @see Pathname
-# @see http://www.rubydoc.info/github/Homebrew/brew/file/share/doc/homebrew/Formula-Cookbook.md Formula Cookbook
+# @see http://www.rubydoc.info/github/Homebrew/brew/file/docs/Formula-Cookbook.md Formula Cookbook
 # @see https://github.com/styleguide/ruby Ruby Style Guide
 #
 # <pre>class Wget < Formula
@@ -1973,7 +1973,7 @@ class Formula
     # and you haven't passed or previously used any options on this formula.
     #
     # If you maintain your own repository, you can add your own bottle links.
-    # https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Bottles.md
+    # https://github.com/Homebrew/brew/blob/master/docs/Bottles.md
     # You can ignore this block entirely if submitting to Homebrew/Homebrew, It'll be
     # handled for you by the Brew Test Bot.
     #
diff --git a/Library/Homebrew/manpages/brew.1.md.erb b/Library/Homebrew/manpages/brew.1.md.erb
index f856b50ee2eaa07d3c70d9876887d591aac93f36..e44dc26584c82b5a8dd4cd5a93bc055e7c8545fb 100644
--- a/Library/Homebrew/manpages/brew.1.md.erb
+++ b/Library/Homebrew/manpages/brew.1.md.erb
@@ -62,7 +62,7 @@ scripts that reside somewhere in the `PATH`, named `brew-`<cmdname> or
 to create your own commands without modifying Homebrew's internals.
 
 Instructions for creating your own commands can be found in the docs:
-<https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/External-Commands.md>
+<https://github.com/Homebrew/brew/blob/master/docs/External-Commands.md>
 
 ## SPECIFYING FORMULAE
 
@@ -183,7 +183,7 @@ can take several different forms:
     *Default:* the number of available CPU cores.
 
   * `HOMEBREW_NO_ANALYTICS`:
-    If set, Homebrew will not send analytics. See: <https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics.md#analytics>
+    If set, Homebrew will not send analytics. See: <https://github.com/Homebrew/brew/blob/master/docs/Analytics.md#analytics>
 
   * `HOMEBREW_NO_AUTO_UPDATE`:
     If set, Homebrew will not auto-update before running `brew install`,
@@ -249,7 +249,7 @@ If your proxy requires authentication:
 
 ## SEE ALSO
 
-Homebrew Documentation: <https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/>
+Homebrew Documentation: <https://github.com/Homebrew/brew/blob/master/docs/>
 
 `git`(1), `git-log`(1)
 
diff --git a/Library/Homebrew/test/test_bash.rb b/Library/Homebrew/test/test_bash.rb
index e965aaf21896aff3ee7a2ecaa86cea59ef4ec0db..ff418c787b576206c77b217cf9324427c6456e92 100644
--- a/Library/Homebrew/test/test_bash.rb
+++ b/Library/Homebrew/test/test_bash.rb
@@ -19,7 +19,7 @@ class BashTests < Homebrew::TestCase
   end
 
   def test_bash_completion
-    script = HOMEBREW_LIBRARY_PATH.parent.parent/"etc/bash_completion.d/brew"
+    script = HOMEBREW_LIBRARY_PATH.parent.parent/"completions/bash/brew"
     assert_valid_bash_syntax script
   end
 
diff --git a/Library/Homebrew/utils.rb b/Library/Homebrew/utils.rb
index 8121b7146558227d5187ba2dfb22f428e9927332..e466f8a08dcb74632b4fc5e295e98701bc92aaaf 100644
--- a/Library/Homebrew/utils.rb
+++ b/Library/Homebrew/utils.rb
@@ -605,8 +605,11 @@ def link_src_dst_dirs(src_dir, dst_dir, command, link_dir: false)
   src_paths = link_dir ? [src_dir] : src_dir.find
   src_paths.each do |src|
     next if src.directory? && !link_dir
-    dst = dst_dir.parent/src.relative_path_from(src_dir.parent)
-    next if dst.symlink? && src == dst.resolved_path
+    dst = dst_dir/src.relative_path_from(src_dir)
+    if dst.symlink?
+      next if src == dst.resolved_path
+      dst.unlink
+    end
     if dst.exist?
       conflicts << dst
       next
diff --git a/Library/Homebrew/utils/analytics.rb b/Library/Homebrew/utils/analytics.rb
index e176f0566b28662d6289265933dbe929bc91e7f7..9066cce73c4eb3956f45283886277d1d7be34c68 100644
--- a/Library/Homebrew/utils/analytics.rb
+++ b/Library/Homebrew/utils/analytics.rb
@@ -35,7 +35,7 @@ module Utils
         end
 
         # Send analytics. Don't send or store any personally identifiable information.
-        # https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics.md
+        # https://github.com/Homebrew/brew/blob/master/docs/Analytics.md
         # https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide
         # https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters
         if ENV["HOMEBREW_ANALYTICS_DEBUG"]
diff --git a/Library/Homebrew/utils/analytics.sh b/Library/Homebrew/utils/analytics.sh
index 0bc58c0be5ea384218c37e347080c3f1bdc8b1ea..24839709e0dc0a526ba9cb70779dc44fed1b5af6 100644
--- a/Library/Homebrew/utils/analytics.sh
+++ b/Library/Homebrew/utils/analytics.sh
@@ -104,7 +104,7 @@ report-analytics-screenview-command() {
   )
 
   # Send analytics. Don't send or store any personally identifiable information.
-  # https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics.md
+  # https://github.com/Homebrew/brew/blob/master/docs/Analytics.md
   # https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide#screenView
   # https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters
   if [[ -z "$HOMEBREW_ANALYTICS_DEBUG" ]]
diff --git a/README.md b/README.md
index dcd06cc7c57a5bed10dc18f2f142011453c54c59..5e3ec976b81c143fc6895d1cae70289d78647506 100644
--- a/README.md
+++ b/README.md
@@ -13,12 +13,12 @@ cd "$(brew --repo)" && git fetch && git reset --hard origin/master && brew updat
 3. Or use `brew search --desc <keyword>` to browse packages from the command line.
 
 ## More Documentation
-`brew help`, `man brew` or check [our documentation](https://github.com/Homebrew/brew/tree/master/share/doc/homebrew#readme).
+`brew help`, `man brew` or check [our documentation](https://github.com/Homebrew/brew/tree/master/docs#readme).
 
 ## Troubleshooting
 First, please run `brew update` and `brew doctor`.
 
-Second, read the [Troubleshooting Checklist](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Troubleshooting.md#troubleshooting).
+Second, read the [Troubleshooting Checklist](https://github.com/Homebrew/brew/blob/master/docs/Troubleshooting.md#troubleshooting).
 
 **If you don't read these it will take us far longer to help you with your problem.**
 
@@ -27,7 +27,7 @@ We'd love you to contribute to Homebrew. First, please read our [Contribution Gu
 
 We explicitly welcome contributions from people who have never contributed to open-source before: we were all beginners once! We can help build on a partially working pull request with the aim of getting it merged. We are also actively seeking to diversify our contributors and especially welcome contributions from women from all backgrounds and people of colour.
 
-A good starting point for contributing is running `brew audit` (or `brew audit --strict`) with some of the packages you use (e.g. `brew audit wget` if you use `wget`) and then read through the warnings, try to fix them until `brew audit` shows no results and [submit a pull request](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md). If no formulae you use have warnings you can run `brew audit` without arguments to have it run on all packages and pick one. Good luck!
+A good starting point for contributing is running `brew audit` (or `brew audit --strict`) with some of the packages you use (e.g. `brew audit wget` if you use `wget`) and then read through the warnings, try to fix them until `brew audit` shows no results and [submit a pull request](https://github.com/Homebrew/brew/blob/master/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md). If no formulae you use have warnings you can run `brew audit` without arguments to have it run on all packages and pick one. Good luck!
 
 ## Security
 Please report security issues to security@brew.sh.
@@ -63,7 +63,7 @@ Homebrew is a member of the [Software Freedom Conservancy](http://sfconservancy.
 - Donate with Flattr or PayPal Giving Fund: coming soon.
 
 ## Sponsors
-Our CI infrastructure was paid for by [our Kickstarter supporters](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Kickstarter-Supporters.md).
+Our CI infrastructure was paid for by [our Kickstarter supporters](https://github.com/Homebrew/brew/blob/master/docs/Kickstarter-Supporters.md).
 
 Our CI infrastructure is hosted by [The Positive Internet Company](http://www.positive-internet.com).
 
diff --git a/etc/bash_completion.d/brew b/completions/bash/brew
similarity index 100%
rename from etc/bash_completion.d/brew
rename to completions/bash/brew
diff --git a/share/zsh/site-functions/_brew b/completions/zsh/_brew
similarity index 100%
rename from share/zsh/site-functions/_brew
rename to completions/zsh/_brew
diff --git a/share/zsh/site-functions/_brew_cask b/completions/zsh/_brew_cask
similarity index 100%
rename from share/zsh/site-functions/_brew_cask
rename to completions/zsh/_brew_cask
diff --git a/share/doc/homebrew/Acceptable-Formulae.md b/docs/Acceptable-Formulae.md
similarity index 100%
rename from share/doc/homebrew/Acceptable-Formulae.md
rename to docs/Acceptable-Formulae.md
diff --git a/share/doc/homebrew/Analytics.md b/docs/Analytics.md
similarity index 100%
rename from share/doc/homebrew/Analytics.md
rename to docs/Analytics.md
diff --git a/share/doc/homebrew/Bottles.md b/docs/Bottles.md
similarity index 100%
rename from share/doc/homebrew/Bottles.md
rename to docs/Bottles.md
diff --git a/share/doc/homebrew/Brew-Test-Bot-For-Core-Contributors.md b/docs/Brew-Test-Bot-For-Core-Contributors.md
similarity index 100%
rename from share/doc/homebrew/Brew-Test-Bot-For-Core-Contributors.md
rename to docs/Brew-Test-Bot-For-Core-Contributors.md
diff --git a/share/doc/homebrew/Brew-Test-Bot.md b/docs/Brew-Test-Bot.md
similarity index 100%
rename from share/doc/homebrew/Brew-Test-Bot.md
rename to docs/Brew-Test-Bot.md
diff --git a/share/doc/homebrew/C++-Standard-Libraries.md b/docs/C++-Standard-Libraries.md
similarity index 100%
rename from share/doc/homebrew/C++-Standard-Libraries.md
rename to docs/C++-Standard-Libraries.md
diff --git a/share/doc/homebrew/Checksum_Deprecation.md b/docs/Checksum_Deprecation.md
similarity index 100%
rename from share/doc/homebrew/Checksum_Deprecation.md
rename to docs/Checksum_Deprecation.md
diff --git a/share/doc/homebrew/Common-Issues-for-Core-Contributors.md b/docs/Common-Issues-for-Core-Contributors.md
similarity index 100%
rename from share/doc/homebrew/Common-Issues-for-Core-Contributors.md
rename to docs/Common-Issues-for-Core-Contributors.md
diff --git a/share/doc/homebrew/Common-Issues.md b/docs/Common-Issues.md
similarity index 98%
rename from share/doc/homebrew/Common-Issues.md
rename to docs/Common-Issues.md
index 320ad6d89ae9ba3749d44a9b26d9820e35faca89..14f2836c414014ac0f1f241de7e7ca73f38bfbb3 100644
--- a/share/doc/homebrew/Common-Issues.md
+++ b/docs/Common-Issues.md
@@ -76,7 +76,7 @@ When running `brew upgrade`, you see something like this:
 $ brew upgrade
 Error: undefined method `include?' for nil:NilClass
 Please report this bug:
-    https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Troubleshooting.md
+    https://github.com/Homebrew/brew/blob/master/docs/Troubleshooting.md
 /usr/local/Library/Homebrew/formula.rb:393:in `canonical_name'
 /usr/local/Library/Homebrew/formula.rb:425:in `factory'
 /usr/local/Library/Contributions/examples/brew-upgrade.rb:7
diff --git a/share/doc/homebrew/Custom-GCC-and-cross-compilers.md b/docs/Custom-GCC-and-cross-compilers.md
similarity index 100%
rename from share/doc/homebrew/Custom-GCC-and-cross-compilers.md
rename to docs/Custom-GCC-and-cross-compilers.md
diff --git a/share/doc/homebrew/External-Commands.md b/docs/External-Commands.md
similarity index 97%
rename from share/doc/homebrew/External-Commands.md
rename to docs/External-Commands.md
index 090b664cb11f7fdcba9cd56d7cede104f2efa4f2..8fe6932b05be363908acde4c7ef89337023e9876 100644
--- a/share/doc/homebrew/External-Commands.md
+++ b/docs/External-Commands.md
@@ -81,4 +81,4 @@ These commands have been contributed by Homebrew users but are not included in t
 > ```
 
 ## SEE ALSO
-Homebrew Docs: <https://github.com/Homebrew/brew/tree/master/share/doc/homebrew>
+Homebrew Docs: <https://github.com/Homebrew/brew/tree/master/docs>
diff --git a/share/doc/homebrew/FAQ.md b/docs/FAQ.md
similarity index 100%
rename from share/doc/homebrew/FAQ.md
rename to docs/FAQ.md
diff --git a/share/doc/homebrew/Formula-Cookbook.md b/docs/Formula-Cookbook.md
similarity index 99%
rename from share/doc/homebrew/Formula-Cookbook.md
rename to docs/Formula-Cookbook.md
index 876a6645fcc6e7f8042d0e2f52a14919ebeb6ba0..40c672a657df4cfd721efd129e037bec893430ea 100644
--- a/share/doc/homebrew/Formula-Cookbook.md
+++ b/docs/Formula-Cookbook.md
@@ -350,7 +350,7 @@ If you have already forked Homebrew on GitHub, then you can manually push (just
 git push https://github.com/myname/homebrew-core/ <what-you-called-your-branch>
 ```
 
-Now, please [open a pull request](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md#how-to-open-a-homebrew-pull-request-and-get-it-merged) for your changes.
+Now, please [open a pull request](https://github.com/Homebrew/brew/blob/master/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md#how-to-open-a-homebrew-pull-request-and-get-it-merged) for your changes.
 
 *   One formula per commit; one commit per formula
 *   Keep merge commits out of the pull request
diff --git a/share/doc/homebrew/Gems,-Eggs-and-Perl-Modules.md b/docs/Gems,-Eggs-and-Perl-Modules.md
similarity index 100%
rename from share/doc/homebrew/Gems,-Eggs-and-Perl-Modules.md
rename to docs/Gems,-Eggs-and-Perl-Modules.md
diff --git a/share/doc/homebrew/Homebrew-and-Python.md b/docs/Homebrew-and-Python.md
similarity index 100%
rename from share/doc/homebrew/Homebrew-and-Python.md
rename to docs/Homebrew-and-Python.md
diff --git a/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md b/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md
similarity index 100%
rename from share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md
rename to docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md
diff --git a/share/doc/homebrew/How-to-Create-and-Maintain-a-Tap.md b/docs/How-to-Create-and-Maintain-a-Tap.md
similarity index 100%
rename from share/doc/homebrew/How-to-Create-and-Maintain-a-Tap.md
rename to docs/How-to-Create-and-Maintain-a-Tap.md
diff --git a/share/doc/homebrew/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md b/docs/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md
similarity index 100%
rename from share/doc/homebrew/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md
rename to docs/How-to-build-software-outside-Homebrew-with-Homebrew-keg-only-dependencies.md
diff --git a/share/doc/homebrew/Installation.md b/docs/Installation.md
similarity index 100%
rename from share/doc/homebrew/Installation.md
rename to docs/Installation.md
diff --git a/share/doc/homebrew/Interesting-Taps-&-Forks.md b/docs/Interesting-Taps-&-Forks.md
similarity index 100%
rename from share/doc/homebrew/Interesting-Taps-&-Forks.md
rename to docs/Interesting-Taps-&-Forks.md
diff --git a/share/doc/homebrew/Kickstarter-Supporters.md b/docs/Kickstarter-Supporters.md
similarity index 100%
rename from share/doc/homebrew/Kickstarter-Supporters.md
rename to docs/Kickstarter-Supporters.md
diff --git a/share/doc/homebrew/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md
similarity index 100%
rename from share/doc/homebrew/Maintainer-Guidelines.md
rename to docs/Maintainer-Guidelines.md
diff --git a/share/doc/homebrew/Maintainers-Avoiding-Burnout.md b/docs/Maintainers-Avoiding-Burnout.md
similarity index 100%
rename from share/doc/homebrew/Maintainers-Avoiding-Burnout.md
rename to docs/Maintainers-Avoiding-Burnout.md
diff --git a/share/doc/homebrew/Migrating-A-Formula-To-A-Tap.md b/docs/Migrating-A-Formula-To-A-Tap.md
similarity index 100%
rename from share/doc/homebrew/Migrating-A-Formula-To-A-Tap.md
rename to docs/Migrating-A-Formula-To-A-Tap.md
diff --git a/share/doc/homebrew/New-Maintainer-Checklist.md b/docs/New-Maintainer-Checklist.md
similarity index 94%
rename from share/doc/homebrew/New-Maintainer-Checklist.md
rename to docs/New-Maintainer-Checklist.md
index c59e1c341d77f2f863da544b8d94c2f800c0795f..2bdff0202e9758f5bb0da424cfc923909d6607b7 100644
--- a/share/doc/homebrew/New-Maintainer-Checklist.md
+++ b/docs/New-Maintainer-Checklist.md
@@ -25,8 +25,8 @@ A few requests:
 - still create your branches on your fork rather than in the main repository
 - if still in doubt please ask for help and we'll help you out - these are
   probably worth a read:
-    - https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Brew-Test-Bot-For-Core-Contributors.md
-    - https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Maintainer-Guidelines.md
+    - https://github.com/Homebrew/brew/blob/master/docs/Brew-Test-Bot-For-Core-Contributors.md
+    - https://github.com/Homebrew/brew/blob/master/docs/Maintainer-Guidelines.md
     - possibly everything else in the documentation
 
 How does that sound?
diff --git a/share/doc/homebrew/Node-for-Formula-Authors.md b/docs/Node-for-Formula-Authors.md
similarity index 98%
rename from share/doc/homebrew/Node-for-Formula-Authors.md
rename to docs/Node-for-Formula-Authors.md
index 642a0f0671254cf38b6ae057fc616472471b872a..c78668a5816871ffdb38647fbe907bedbe6fb90e 100644
--- a/share/doc/homebrew/Node-for-Formula-Authors.md
+++ b/docs/Node-for-Formula-Authors.md
@@ -82,7 +82,7 @@ In your formula's `install` method, do any installation steps which need to be d
 system "npm", "install", *Language::Node.local_npm_install_args
 ```
 
-This will install all of your Node modules dependencies to your local build path. You can now continue with your build steps and take care of the installation into the Homebrew `prefix` by your own, following the [general Homebrew formula instructions](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Formula-Cookbook.md).
+This will install all of your Node modules dependencies to your local build path. You can now continue with your build steps and take care of the installation into the Homebrew `prefix` by your own, following the [general Homebrew formula instructions](https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md).
 
 # Example
 
diff --git a/share/doc/homebrew/Prose-Style-Guidelines.md b/docs/Prose-Style-Guidelines.md
similarity index 97%
rename from share/doc/homebrew/Prose-Style-Guidelines.md
rename to docs/Prose-Style-Guidelines.md
index 8c4f1d1f09d7ef9988c65439b05079ac9a86a1c9..1d8e2b0fce6282acdbd311bb22978fe300c91430 100644
--- a/share/doc/homebrew/Prose-Style-Guidelines.md
+++ b/docs/Prose-Style-Guidelines.md
@@ -1,6 +1,6 @@
 # Prose Style Guidelines
 
-This is a set of style and usage guidelines for Homebrew's prose documentation aimed at users, contributors, and maintainers (as opposed to executable computer code). It applies to documents like those in `share/doc/homebrew` in the `Homebrew/brew` repo, announcement emails, and other communications with the Homebrew community.
+This is a set of style and usage guidelines for Homebrew's prose documentation aimed at users, contributors, and maintainers (as opposed to executable computer code). It applies to documents like those in `docs` in the `Homebrew/brew` repo, announcement emails, and other communications with the Homebrew community.
 
 This does not apply to any Ruby or other computer code. You can use it to inform technical documentation extracted from computer code, like embedded man pages, but it's just a suggestion there.
 
diff --git a/share/doc/homebrew/Python-for-Formula-Authors.md b/docs/Python-for-Formula-Authors.md
similarity index 100%
rename from share/doc/homebrew/Python-for-Formula-Authors.md
rename to docs/Python-for-Formula-Authors.md
diff --git a/share/doc/homebrew/Querying-Brew.md b/docs/Querying-Brew.md
similarity index 100%
rename from share/doc/homebrew/Querying-Brew.md
rename to docs/Querying-Brew.md
diff --git a/share/doc/homebrew/README.md b/docs/README.md
similarity index 100%
rename from share/doc/homebrew/README.md
rename to docs/README.md
diff --git a/share/doc/homebrew/Rename-A-Formula.md b/docs/Rename-A-Formula.md
similarity index 100%
rename from share/doc/homebrew/Rename-A-Formula.md
rename to docs/Rename-A-Formula.md
diff --git a/share/doc/homebrew/Tips-N'-Tricks.md b/docs/Tips-N'-Tricks.md
similarity index 97%
rename from share/doc/homebrew/Tips-N'-Tricks.md
rename to docs/Tips-N'-Tricks.md
index e97f740ed3515fba94838d5bf88f77bab8a1e56f..d3ed83fd2fc4ef126435edb55e2393e601e3bb84 100644
--- a/share/doc/homebrew/Tips-N'-Tricks.md
+++ b/docs/Tips-N'-Tricks.md
@@ -6,7 +6,7 @@ The preferred and supported method of installing specific versions of
 formulae is to use the
 [homebrew/versions](https://github.com/Homebrew/homebrew-versions)
 tap.  If the version you鈥檙e looking for isn鈥檛 available, consider [opening a
-pull request](https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md)!
+pull request](https://github.com/Homebrew/brew/blob/master/docs/How-To-Open-a-Homebrew-Pull-Request-(and-get-it-merged).md)!
 
 ### Installing directly from pull-requests
 
diff --git a/share/doc/homebrew/Troubleshooting.md b/docs/Troubleshooting.md
similarity index 100%
rename from share/doc/homebrew/Troubleshooting.md
rename to docs/Troubleshooting.md
diff --git a/share/doc/homebrew/Xcode.md b/docs/Xcode.md
similarity index 100%
rename from share/doc/homebrew/Xcode.md
rename to docs/Xcode.md
diff --git a/share/doc/homebrew/brew-tap.md b/docs/brew-tap.md
similarity index 100%
rename from share/doc/homebrew/brew-tap.md
rename to docs/brew-tap.md
diff --git a/share/doc/homebrew/brew.1.html b/docs/brew.1.html
similarity index 98%
rename from share/doc/homebrew/brew.1.html
rename to docs/brew.1.html
index 7e1e04e94d6ff1f0255bbadb6a2ba05d7dad61ef..b6c4be7184888391b4af248818dd34128a606a70 100644
--- a/share/doc/homebrew/brew.1.html
+++ b/docs/brew.1.html
@@ -151,7 +151,7 @@ for <var>version</var> is <code>v1</code>.</p>
 information on all installed formulae.</p>
 
 <p>See the docs for examples of using the JSON:
-<a href="https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md</a></p></dd>
+<a href="https://github.com/Homebrew/brew/blob/master/docs/Querying-Brew.md" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/docs/Querying-Brew.md</a></p></dd>
 <dt><code>install</code> [<code>--debug</code>] [<code>--env=</code><var>std</var>|<var>super</var>] [<code>--ignore-dependencies</code>] [<code>--only-dependencies</code>] [<code>--cc=</code><var>compiler</var>] [<code>--build-from-source</code>] [<code>--devel</code>|<code>--HEAD</code>] [<code>--keep-tmp</code>] <var>formula</var></dt><dd><p>Install <var>formula</var>.</p>
 
 <p><var>formula</var> is usually the name of the formula to install, but it can be specified
@@ -344,7 +344,7 @@ for <var>version</var> is <code>v1</code>.</p>
 <p>Pass <code>--installed</code> to get information on installed taps.</p>
 
 <p>See the docs for examples of using the JSON:
-<a href="https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying-Brew.md</a></p></dd>
+<a href="https://github.com/Homebrew/brew/blob/master/docs/Querying-Brew.md" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/docs/Querying-Brew.md</a></p></dd>
 <dt><code>tap-pin</code> <var>tap</var></dt><dd><p>Pin <var>tap</var>, prioritizing its formulae over core when formula names are supplied
 by the user. See also <code>tap-unpin</code>.</p></dd>
 <dt><code>tap-unpin</code> <var>tap</var></dt><dd><p>Unpin <var>tap</var> so its formulae are no longer prioritized. See also <code>tap-pin</code>.</p></dd>
@@ -590,7 +590,7 @@ scripts that reside somewhere in the <code>PATH</code>, named <code>brew-</code>
 to create your own commands without modifying Homebrew's internals.</p>
 
 <p>Instructions for creating your own commands can be found in the docs:
-<a href="https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/External-Commands.md" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/External-Commands.md</a></p>
+<a href="https://github.com/Homebrew/brew/blob/master/docs/External-Commands.md" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/docs/External-Commands.md</a></p>
 
 <h2 id="SPECIFYING-FORMULAE">SPECIFYING FORMULAE</h2>
 
@@ -669,7 +669,7 @@ Homebrew uses the GitHub API for features such as <code>brew search</code>.</p>
 the number of parallel jobs to run when building with <code>make</code>(1).</p>
 
 <p><em>Default:</em> the number of available CPU cores.</p></dd>
-<dt><code>HOMEBREW_NO_ANALYTICS</code></dt><dd><p>If set, Homebrew will not send analytics. See: <a href="https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics.md#analytics" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics.md#analytics</a></p></dd>
+<dt><code>HOMEBREW_NO_ANALYTICS</code></dt><dd><p>If set, Homebrew will not send analytics. See: <a href="https://github.com/Homebrew/brew/blob/master/docs/Analytics.md#analytics" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/docs/Analytics.md#analytics</a></p></dd>
 <dt><code>HOMEBREW_NO_AUTO_UPDATE</code></dt><dd><p>If set, Homebrew will not auto-update before running <code>brew install</code>,
 <code>brew upgrade</code> or <code>brew tap</code>.</p></dd>
 <dt><code>HOMEBREW_NO_EMOJI</code></dt><dd><p>If set, Homebrew will not print the <code>HOMEBREW_INSTALL_BADGE</code> on a
@@ -721,7 +721,7 @@ your shell profile, or you can use it before a brew command:</p>
 
 <h2 id="SEE-ALSO">SEE ALSO</h2>
 
-<p>Homebrew Documentation: <a href="https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/</a></p>
+<p>Homebrew Documentation: <a href="https://github.com/Homebrew/brew/blob/master/docs/" data-bare-link="true">https://github.com/Homebrew/brew/blob/master/docs/</a></p>
 
 <p><code>git</code>(1), <code>git-log</code>(1)</p>
 
diff --git a/share/doc/homebrew/images/analytics.png b/docs/images/analytics.png
similarity index 100%
rename from share/doc/homebrew/images/analytics.png
rename to docs/images/analytics.png
diff --git a/share/doc/homebrew/images/brew-test-bot-failed-jenkins.png b/docs/images/brew-test-bot-failed-jenkins.png
similarity index 100%
rename from share/doc/homebrew/images/brew-test-bot-failed-jenkins.png
rename to docs/images/brew-test-bot-failed-jenkins.png
diff --git a/share/doc/homebrew/images/brew-test-bot-failed-pr.png b/docs/images/brew-test-bot-failed-pr.png
similarity index 100%
rename from share/doc/homebrew/images/brew-test-bot-failed-pr.png
rename to docs/images/brew-test-bot-failed-pr.png
diff --git a/share/doc/homebrew/images/brew-test-bot-failed-test.png b/docs/images/brew-test-bot-failed-test.png
similarity index 100%
rename from share/doc/homebrew/images/brew-test-bot-failed-test.png
rename to docs/images/brew-test-bot-failed-test.png
diff --git a/share/doc/homebrew/images/brew-test-bot-passed-jenkins.png b/docs/images/brew-test-bot-passed-jenkins.png
similarity index 100%
rename from share/doc/homebrew/images/brew-test-bot-passed-jenkins.png
rename to docs/images/brew-test-bot-passed-jenkins.png
diff --git a/share/doc/homebrew/images/brew-test-bot-passed-pr.png b/docs/images/brew-test-bot-passed-pr.png
similarity index 100%
rename from share/doc/homebrew/images/brew-test-bot-passed-pr.png
rename to docs/images/brew-test-bot-passed-pr.png
diff --git a/share/doc/homebrew/images/brew-test-bot-triggered-pr.png b/docs/images/brew-test-bot-triggered-pr.png
similarity index 100%
rename from share/doc/homebrew/images/brew-test-bot-triggered-pr.png
rename to docs/images/brew-test-bot-triggered-pr.png
diff --git a/share/man/man1/brew-cask.1 b/manpages/brew-cask.1
similarity index 100%
rename from share/man/man1/brew-cask.1
rename to manpages/brew-cask.1
diff --git a/share/man/man1/brew.1 b/manpages/brew.1
similarity index 99%
rename from share/man/man1/brew.1
rename to manpages/brew.1
index 532c0fc91669b02988b9d689b8fc4225b1f2c811..c4a650335717ea27c8f89959256d0cdfdc1e7e14 100644
--- a/share/man/man1/brew.1
+++ b/manpages/brew.1
@@ -213,7 +213,7 @@ Print a JSON representation of \fIformulae\fR\. Currently the only accepted valu
 Pass \fB\-\-all\fR to get information on all formulae, or \fB\-\-installed\fR to get information on all installed formulae\.
 .
 .IP
-See the docs for examples of using the JSON: \fIhttps://github\.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying\-Brew\.md\fR
+See the docs for examples of using the JSON: \fIhttps://github\.com/Homebrew/brew/blob/master/docs/Querying\-Brew\.md\fR
 .
 .TP
 \fBinstall\fR [\fB\-\-debug\fR] [\fB\-\-env=\fR\fIstd\fR|\fIsuper\fR] [\fB\-\-ignore\-dependencies\fR] [\fB\-\-only\-dependencies\fR] [\fB\-\-cc=\fR\fIcompiler\fR] [\fB\-\-build\-from\-source\fR] [\fB\-\-devel\fR|\fB\-\-HEAD\fR] [\fB\-\-keep\-tmp\fR] \fIformula\fR
@@ -473,7 +473,7 @@ Print a JSON representation of \fItaps\fR\. Currently the only accepted value fo
 Pass \fB\-\-installed\fR to get information on installed taps\.
 .
 .IP
-See the docs for examples of using the JSON: \fIhttps://github\.com/Homebrew/brew/blob/master/share/doc/homebrew/Querying\-Brew\.md\fR
+See the docs for examples of using the JSON: \fIhttps://github\.com/Homebrew/brew/blob/master/docs/Querying\-Brew\.md\fR
 .
 .TP
 \fBtap\-pin\fR \fItap\fR
@@ -790,7 +790,7 @@ If \fB\-\-keep\-tmp\fR is passed, retain the temporary directory containing the
 Homebrew, like \fBgit\fR(1), supports external commands\. These are executable scripts that reside somewhere in the \fBPATH\fR, named \fBbrew\-\fR\fIcmdname\fR or \fBbrew\-\fR\fIcmdname\fR\fB\.rb\fR, which can be invoked like \fBbrew\fR \fIcmdname\fR\. This allows you to create your own commands without modifying Homebrew\'s internals\.
 .
 .P
-Instructions for creating your own commands can be found in the docs: \fIhttps://github\.com/Homebrew/brew/blob/master/share/doc/homebrew/External\-Commands\.md\fR
+Instructions for creating your own commands can be found in the docs: \fIhttps://github\.com/Homebrew/brew/blob/master/docs/External\-Commands\.md\fR
 .
 .SH "SPECIFYING FORMULAE"
 Many Homebrew commands accept one or more \fIformula\fR arguments\. These arguments can take several different forms:
@@ -909,7 +909,7 @@ If set, instructs Homebrew to use the value of \fBHOMEBREW_MAKE_JOBS\fR as the n
 .
 .TP
 \fBHOMEBREW_NO_ANALYTICS\fR
-If set, Homebrew will not send analytics\. See: \fIhttps://github\.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics\.md#analytics\fR
+If set, Homebrew will not send analytics\. See: \fIhttps://github\.com/Homebrew/brew/blob/master/docs/Analytics\.md#analytics\fR
 .
 .TP
 \fBHOMEBREW_NO_AUTO_UPDATE\fR
@@ -989,7 +989,7 @@ http_proxy=http://<user>:<password>@<host>:<port> brew install foo
 .IP "" 0
 .
 .SH "SEE ALSO"
-Homebrew Documentation: \fIhttps://github\.com/Homebrew/brew/blob/master/share/doc/homebrew/\fR
+Homebrew Documentation: \fIhttps://github\.com/Homebrew/brew/blob/master/docs/\fR
 .
 .P
 \fBgit\fR(1), \fBgit\-log\fR(1)
@@ -1013,4 +1013,3 @@ Homebrew/brew \fIhttps://github\.com/Homebrew/brew/issues\fR
 Homebrew/homebrew\-core \fIhttps://github\.com/Homebrew/homebrew\-core/issues\fR
 .
 .IP "" 0
-