diff --git a/pyerrors/__init__.py b/pyerrors/__init__.py
index febb390a..8c0b8483 100644
--- a/pyerrors/__init__.py
+++ b/pyerrors/__init__.py
@@ -21,13 +21,50 @@ my_new_obs.details()
 print(my_new_obs)
 ```
 # The `Obs` class
-`pyerrors.obs.Obs`
+
+`pyerrors` introduces a new datatype, `Obs`, which simplifies error propagation and estimation for auto- and cross-correlated data.
+An `Obs` object can be initialized with two arguments, the first is a list containining the samples for an Observable from a Monte Carlo chain.
+The samples can either be provided as python list or as numpy array.
+The second argument is a list containing the names of the respective Monte Carlo chains as strings. These strings uniquely identify a Monte Carlo chain/ensemble.
+
+Example:
 ```python
 import pyerrors as pe
 
 my_obs = pe.Obs([samples], ['ensemble_name'])
 ```
 
+## Error propagation
+
+When performing mathematical operations on `Obs` objects the correct error propagation is intrinsically taken care using a first order Taylor expansion
+$$\delta_f^i=\sum_\alpha \bar{f}_\alpha \delta_\alpha^i\,,\quad \delta_\alpha^i=a_\alpha^i-\bar{a}_\alpha$$
+as introduced in [arXiv:hep-lat/0306017](https://arxiv.org/abs/hep-lat/0306017).
+
+The required derivatives $\bar{f}_\alpha$ are evaluated up to machine precision via automatic differentiation as suggested in [arXiv:1809.01289](https://arxiv.org/abs/1809.01289).
+
+The `Obs` class is designed such that mathematical numpy functions can be used on `Obs` just as for regular floats.
+
+Example:
+```python
+import numpy as np
+import pyerrors as pe
+
+my_obs1 = pe.Obs([samples1], ['ensemble_name'])
+my_obs2 = pe.Obs([samples2], ['ensemble_name'])
+
+my_sum = my_obs1 + my_obs2
+
+my_m_eff = np.log(my_obs1 / my_obs2)
+```
+
+## Error estimation
+
+The error propagation is based on the gamma method introduced in [arXiv:hep-lat/0306017](https://arxiv.org/abs/hep-lat/0306017).
+
+
+For the full API see `pyerrors.obs.Obs.gamma_method`
+### Exponential tails
+
 ## Multiple ensembles/replica
 
 Error propagation for multiple ensembles (Markov chains with different simulation parameters) is handeled automatically. Ensembles are uniquely identified by their `name`.
@@ -78,40 +115,18 @@ obs3 = pe.Obs([samples3], ['ensemble1'], idl=[[2, 9, 28, 29, 501]])
 **Warning:** Irregular Monte Carlo chains can result in odd patterns in the autocorrelation functions.
 Make sure to check the with e.g. `pyerrors.obs.Obs.plot_rho` or `pyerrors.obs.Obs.plot_tauint`.
 
-# Error propagation
-Automatic differentiation, [arXiv:1809.01289](https://arxiv.org/abs/1809.01289)
-
-numpy overloaded
-```python
-import numpy as np
-import pyerrors as pe
-
-my_obs = pe.Obs([samples], ['ensemble_name'])
-my_new_obs = 2 * np.log(my_obs) / my_obs
-my_new_obs.gamma_method()
-my_new_obs.details()
-```
-
-# Error estimation
-`pyerrors.obs.Obs.gamma_method`
-
-$\delta_i\delta_j$
-
-## Exponential tails
-
-## Covariance
+For the full API see `pyerrors.obs.Obs`
 
 # Correlators
-`pyerrors.correlators.Corr`
+For the full API see `pyerrors.correlators.Corr`
+
+# Complex observables
+`pyerrors.obs.CObs`
 
 # Optimization / fits / roots
 `pyerrors.fits`
 `pyerrors.roots`
 
-
-# Complex observables
-`pyerrors.obs.CObs`
-
 # Matrix operations
 `pyerrors.linalg`