Reorder IO docs (#1644)

docs/api.md

@@ -15,7 +15,8 @@ The central class:
 
 ## Combining
 
-Combining AnnData objects. See also the section on concatenation.
+Combining {class}`AnnData` objects.
+See also the section on concatenation.
 
 ```{eval-rst}
 .. autosummary::
@@ -26,83 +27,85 @@ Combining AnnData objects. See also the section on concatenation.
 
 ## Reading
 
-Reading anndata’s native file format `.h5ad`.
+Reading anndata’s native formats `.h5ad` and `zarr`.
 
 ```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
    read_h5ad
+   read_zarr
 ```
 
-Reading other file formats.
+Reading individual portions ({attr}`~AnnData.obs`, {attr}`~AnnData.varm` etc.) of the {class}`AnnData` object.
 
 ```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
-   read_csv
-   read_excel
-   read_hdf
-   read_loom
-   read_mtx
-   read_text
-   read_umi_tools
-   read_zarr
-
+   read_elem
+   sparse_dataset
 ```
 
-Reading individual portions (`obs`, `varm` etc.) of the `AnnData` object.
+Reading file formats that cannot represent all aspects of {class}`AnnData` objects.
+
+```{tip}
+You might have more success by assembling the {class}`AnnData` object yourself from the individual parts.
+```
 
 ```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
-   read_elem
-   sparse_dataset
+   read_csv
+   read_excel
+   read_hdf
+   read_loom
+   read_mtx
+   read_text
+   read_umi_tools
 ```
 
 ## Writing
 
-Writing to anndata’s native file format `.h5ad`.
+Writing a complete {class}`AnnData` object to disk in anndata’s native formats `.h5ad` and `zarr`.
 
 ```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
    AnnData.write
+   AnnData.write_zarr
 ```
 
-Writing to other formats.
+Writing individual portions ({attr}`~AnnData.obs`, {attr}`~AnnData.varm` etc.) of the {class}`AnnData` object.
 
 ```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
-   AnnData.write_csvs
-   AnnData.write_loom
-   AnnData.write_zarr
+   write_elem
 ```
 
-Writing individual portions (`obs`, `varm` etc.) of the `AnnData` object.
+Writing formats that cannot represent all aspects of {class}`AnnData` objects.
 
 ```{eval-rst}
 .. autosummary::
    :toctree: generated/
 
-   write_elem
-
+   AnnData.write_csvs
+   AnnData.write_loom
 ```
 
 (experimental-api)=
 
 ## Experimental API
 
 ```{warning}
-API's in the experimental module are currently in development and subject to change at any time.
+APIs in the experimental module are currently in development and subject to change at any time.
 ```
 
-Two classes for working with batched access to collections of many `AnnData` objects or `h5ad` files.
+Two classes for working with batched access to collections of many {class}`AnnData` objects or `.h5ad` files.
 In particular, for pytorch-based models.
 
 ```{eval-rst}
@@ -122,7 +125,7 @@ Out of core concatenation
    experimental.concat_on_disk
 ```
 
-Low level methods for reading and writing elements of an `AnnData` object to a store:
+Low level methods for reading and writing elements of an {class}`AnnData` object to a store:
 
 ```{eval-rst}
 .. autosummary::