DOC: general discussion of our docstring sharing system
Currently in many places we write docstrings as string values inside a `_shared_docs` dictionary, and then add this docstring to the method with a decorator like `@Appender(_shared_docs['where'])`, or possibly with substitution of variables in the template docstring with `@Appender(_shared_docs['where'] % _shared_doc_kwargs)`. 
Apart from that, we have some other custom ways to generate them, typically for a specific set of methods (eg all statistical methods like mean, sum, median, ..).

This system is important to not duplicate content too much, but also has some drawbacks:

- I think it is a rather complex system for contributors to understand. It can be hard to know where to find the method's docstring, or how to edit it appropriately, and how it will look like eventually.
- It gives rise to some errors (which can of course be solved). For example:
  - left-overs from shared_kwargs of parent docstrings that have not been substituted correctly. Eg NDFrame should never occur in the docs, but does quite a lot (eg [DataFrame.where docstring](http://pandas.pydata.org/pandas-docs/version/0.22/generated/pandas.DataFrame.where.html))
  - left-overs of the template where we forgot to substitute at all (eg [DataFrame.rename docstring](http://pandas.pydata.org/pandas-docs/version/0.22/generated/pandas.DataFrame.rename.html))
- We have examples that are not specific for the function (eg [DataFrame.mask docstring](http://pandas.pydata.org/pandas-docs/version/0.22/generated/pandas.DataFrame.mask.html) with DataFrame.where examples) or for the object (eg [Index.searchsorted docstring](http://pandas.pydata.org/pandas-docs/version/0.22/generated/pandas.Index.searchsorted.html) with Series examples). 
 And in general in can be hard/complicated to add good examples, as those are typically specific to one method, so you need to write them in separate strings and then add to the appropriate docstring.

So therefore opening this issue, to gather ideas on whether we can improve this workflow, without sacrificing the deduplication and flexibility of the current system?