DOC: Restructured the documentation

Author: pfrcks

doc/source/basics.rst

@@ -1726,22 +1726,26 @@ then the more *general* one will be used as the result of the operation.
    # conversion of dtypes
    df3.astype('float32').dtypes
 
-When trying to convert a subset of columns to a specified type using :meth:`~DataFrame.astype`  and :meth:`~DataFrame.loc`, utilizing **:** as mask, upcasting occurs.
-:meth:`~DataFrame.loc` tries to fit in what we are assigning to the current dtypes, while [ ] will overwrite them taking the dtype from the right hand side.
+Convert a subset of columns to a specified type using :meth:`~DataFrame.astype`
 
 .. ipython:: python
 
    df = pd.DataFrame({'a': [1,2,3], 'b': [4,5,6], 'c': [7, 8, 9]})
-   df.loc[:, ['a', 'b']].astype(np.uint8).dtypes
-   df.loc[:, ['a', 'b']] = df.loc[:, ['a', 'b']].astype(np.uint8)
+   df[['a','b']] = df[['a','b']].astype(np.uint8)
+   df
+   df.dtypes
+
+.. note::
+
+    When trying to convert a subset of columns to a specified type using :meth:`~DataFrame.astype`  and :meth:`~DataFrame.loc`, utilizing **:** as mask, upcasting occurs.
 
-To avoid this please take the following approach.
+    :meth:`~DataFrame.loc` tries to fit in what we are assigning to the current dtypes, while [ ] will overwrite them taking the dtype from the right hand side. Therefore the following piece of code produces the unintended result.
 
 .. ipython:: python
 
    df = pd.DataFrame({'a': [1,2,3], 'b': [4,5,6], 'c': [7, 8, 9]})
-   df[['a','b']] = df[['a','b']].astype(np.uint8)
-   df
+   df.loc[:, ['a', 'b']].astype(np.uint8).dtypes
+   df.loc[:, ['a', 'b']] = df.loc[:, ['a', 'b']].astype(np.uint8)
    df.dtypes
 
 object conversion