better docs

Author: jreback

doc/source/whatsnew/v0.20.0.txt

@@ -128,9 +128,37 @@ Pickle and HDF5 compat requires >= 0.13.0
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ``pd.TimeSeries`` was deprecated officially in 0.17.0, though has only been an alias since 0.13.0. It has
-been dropped in favor of ``pd.Series``.
+been dropped in favor of ``pd.Series``. (:issue:``15098).
+
+This *may* cause pickles / HDF5 files that were created in prior versions to become unreadable if ``pd.TimeSeries``
+was used. If you find yourself in this situation. You can use a recent prior version of pandas to read in
+your pickle / HDF5 files, then write them out again after applying the procedure below.
+
+  .. code-block:: ipython
+
+  In [2]: s = pd.TimeSeries([1,2,3], index=pd.date_range('20130101', periods=3))
+  In [3]: s
+  Out[3]:
+  2013-01-01    1
+  2013-01-02    2
+  2013-01-03    3
+  Freq: D, dtype: int64
+
+  In [4]: type(s)
+  Out[4]: pandas.core.series.TimeSeries
+
+  In [5]: s = pd.Series(s)
+
+  In [6]: s
+  Out[6]:
+  2013-01-01    1
+  2013-01-02    2
+  2013-01-03    3
+  Freq: D, dtype: int64
+
+  In [7]: type(s)
+  Out[7]: pandas.core.series.Series
 
-This *may* cause pickles / HDF5 files that were created with the ``pd.TimeSeries`` to become unreadable. (:issue:``15098).
 
 .. _whatsnew.api_breaking.index_map