diff --git a/R/box.R b/R/box.R
index 8490ed3..eb1b9fc 100644
--- a/R/box.R
+++ b/R/box.R
@@ -23,6 +23,7 @@
 #'
 #' @seealso \href{https://docs.opensensemap.org/#api-Measurements-findAllBoxes}{openSenseMap API documentation (web)}
 #' @seealso \code{\link{osem_phenomena}}
+#' @seealso \code{\link{osem_box}}
 #' @export
 #' @examples
 #' # get *all* boxes available on the API
@@ -78,6 +79,7 @@ osem_boxes = function (exposure = NA, model = NA, grouptag = NA,
 #'
 #' @seealso \href{https://docs.opensensemap.org/#api-Measurements-findAllBoxes}{openSenseMap API documentation (web)}
 #' @seealso \code{\link{osem_phenomena}}
+#' @seealso \code{\link{osem_boxes}}
 #' @export
 #' @examples
 #' # get a specific box by ID
diff --git a/R/opensensmapr.R b/R/opensensmapr.R
index 19c49f3..266be7d 100644
--- a/R/opensensmapr.R
+++ b/R/opensensmapr.R
@@ -1,24 +1,76 @@
-#' opensensmapr: Work with sensor data from opensensemap.org
+#' opensensmapr: Get sensor data from opensensemap.org
 #'
-#' The opensensmapr package provides three categories functions:
-#' \enumerate{
-#'   \item retrieval of senseBoxes
-#'   \item retrieval of measurements
-#'   \item general stats about the openSenseMap database
+#' The opensensmapr package provides functions for
+#' \itemize{
+#'   \item retrieval of senseBox metadata,
+#'   \item retrieval of senseBox measurements,
+#'   \item general statistics about the openSenseMap database.
 #' }
+#' Additionally, helper functions are provided to ease the integration with the
+#' \code{\link{sf}} package for spatial analysis as well as \code{\link{deplyr}}
+#' for general data handling.
 #'
 #' @section Retrieving senseBox metadata:
-#' TODO
+#' On the openSenseMap, measurements are provided by sensors which are assigned
+#' to a sensor station ("senseBox").
+#' A senseBox consists of a collection of sensors, a location (-history), an ID,
+#' as well as metadata about its owner & placement.
+#' senseBoxes can be retrieved either by ID, or as a collection with optional
+#' filters on their metadata
+#' \itemize{
+#'   \item \code{\link{osem_box}}: Get metadata about a single box
+#'     by its ID.
+#'   \item \code{\link{osem_boxes}}: Get metadata about a all
+#'     boxes. Optionally filtered by their attributes.
+#' }
+#'
+#' The data is returned as a \code{\link{data.frame}} with the class
+#' \code{sensebox} attached.
+#' To help in getting an overview of the dataset additional functions are
+#' implemented:
+#' \itemize{
+#'   \item \code{summary.sensebox()}: Aggregate the metadata about the given
+#'     list of senseBoxes.
+#'   \item \code{plot.sensebox()}: Shows the spatial distribution of the given
+#'     list of senseBoxes on a map. Requires additional packages!
+#'   \item \code{\link{osem_phenomena}}: Get a named list with
+#'     counts of the measured phenomena of the given list of senseBoxes.
+#' }
 #'
 #' @section Retrieving measurements:
-#' TODO
+#' Measurements can be retrieved through \code{\link{osem_measurements}} for a
+#' given phenomenon only. A subset of measurements may be selected by
+#'
+#' \itemize{
+#'   \item a list of senseBoxes, previously retrieved through
+#'     \code{\link{osem_box}} or \code{\link{osem_boxes}}.
+#'   \item a geographic bounding box, which can be generated with the
+#'     \code{\link{sf}} package.
+#'   \item a time frame
+#'   \item a exposure type of the given box
+#' }
+#'
+#' Data is returned as \code{data.frame} with the class \code{osem_measurements}.
+#' The provided columns may
 #'
 #' @section Retrieving statistics:
-#' TODO
+#' Count statistics about the database are provided with \code{\link{osem_counts}}.
 #'
-#' @section Working with spatial data from openSenseMap:
-#' TODO
+#' @section Integration with other packages:
+#' The package aims to be compatible with the tidyverse.
+#' Helpers are implemented to ease the further usage of the retrieved data:
+#'
+#' \itemize{
+#'   \item \code{\link{st_as_sf.sensebox}} & \code{\link{st_as_sf.osem_measurements}}:
+#'     Transform the senseBoxes or measurements into an \code{\link{sf}}
+#'     compatible format for spatial analysis.
+#'   \item \code{filter.sensebox()} & \code{mutate.sensebox()}: for use with
+#'     \code{\link{deplyr}}.
+#' }
 #'
+#' @seealso Report bugs at \url{https://github.com/noerw/opensensmapR/issues}
+#' @seealso openSenseMap API: \url{https://api.opensensemap.org/}
+#' @seealso official openSenseMap API documentation: \url{https://docs.opensensemap.org/}
 #' @docType package
 #' @name opensensmapr
 '_PACKAGE'
diff --git a/README.md b/README.md
index 3aec00e..ab1cb72 100644
--- a/README.md
+++ b/README.md
@@ -3,16 +3,7 @@ This R package ingests data (environmental measurements, sensor stations) from
 the API of opensensemap.org for analysis in R.
 The package aims to be compatible with sf and the tidyverse.
 
-> *Whats up with that package name?* idk, the R people seem to [enjoy][1]
-[dropping][2] [vovels][3] so.. Unfortunately I couldn't fit the naming
-convention to drop an `y` in there.
-
-[1]: https://github.com/tidyverse/readr
-[2]: https://github.com/tidyverse/dplyr
-[3]: https://github.com/tidyverse/tidyr
-
 ## Installation
-
 Right now, the package is not on CRAN. To install it from GitHub, run:
 
 ```r
@@ -21,8 +12,10 @@ devtools::install_github('noerw/opensensmapr')
 ```
 
 ## Usage
-A usage example is shown in the vignette [`osem-intro`](https://noerw.github.com/opensensmapR/inst/doc/osem-intro.html).
-In general these are the main functions for data retrieval:
+A verbose usage example is shown in the vignette [`osem-intro`](https://noerw.github.com/opensensmapR/inst/doc/osem-intro.html).
+Each functions documentation can be viewed with `?<function-name>`. An overview
+is given in `?opensensmapr`.
+In short, the following pseudocode shows the main functions for data retrieval:
 
 ```r
 # retrieve a single box by id, or many boxes by some property-filters
@@ -45,7 +38,19 @@ osem_counts()
 
 Additionally there are some helpers: `summary.sensebox(), plot.sensebox(), st_as_sf.sensebox(), [.sensebox(), filter.sensebox(), mutate.sensebox(), ...`.
 
-For parameter usage, open each functions' documentation by calling `?<function-name>`.
+## Changelog
+This project adheres to semantic versioning, for changes in recent versions
+please consult [CHANGES.md](CHANGES.md).
+
+## FAQ
+- *Why does `osem_measurements(phenomenon)` not work?* See [#6](https://github.com/noerw/opensensmapR/issues/6).
+- *Whats up with that package name?* idk, the R people seem to [enjoy][1]
+[dropping][2] [vovels][3] so.. Unfortunately I couldn't fit the naming
+convention to drop an `y` in there.
+
+[1]: https://github.com/tidyverse/readr
+[2]: https://github.com/tidyverse/dplyr
+[3]: https://github.com/tidyverse/tidyr
 
 ## License
 GPL-2.0 - Norwin Roosen
diff --git a/man/opensensmapr.Rd b/man/opensensmapr.Rd
index 0a35cd7..39f4ab2 100644
--- a/man/opensensmapr.Rd
+++ b/man/opensensmapr.Rd
@@ -5,40 +5,88 @@
 \alias{opensensmapr}
 \alias{opensensmapr-package}
 \alias{opensensmapr-package}
-\title{opensensmapr: Work with sensor data from opensensemap.org}
+\title{opensensmapr: Get sensor data from opensensemap.org}
 \description{
-The opensensmapr package provides three categories functions:
-\enumerate{
-  \item retrieval of senseBoxes
-  \item retrieval of measurements
-  \item general stats about the openSenseMap database
+The opensensmapr package provides functions for
+\itemize{
+  \item retrieval of senseBox metadata,
+  \item retrieval of senseBox measurements,
+  \item general statistics about the openSenseMap database.
 }
+Additionally, helper functions are provided to ease the integration with the
+\code{\link{sf}} package for spatial analysis as well as \code{\link{deplyr}}
+for general data handling.
 }
 \section{Retrieving senseBox metadata}{
 
-TODO
+On the openSenseMap, measurements are provided by sensors which are assigned
+to a sensor station ("senseBox").
+A senseBox consists of a collection of sensors, a location (-history), an ID,
+as well as metadata about its owner & placement.
+senseBoxes can be retrieved either by ID, or as a collection with optional
+filters on their metadata
+\itemize{
+  \item \code{\link{osem_box}}: Get metadata about a single box
+    by its ID.
+  \item \code{\link{osem_boxes}}: Get metadata about a all
+    boxes. Optionally filtered by their attributes.
+}
+
+The data is returned as a \code{\link{data.frame}} with the class
+\code{sensebox} attached.
+To help in getting an overview of the dataset additional functions are
+implemented:
+\itemize{
+  \item \code{summary.sensebox()}: Aggregate the metadata about the given
+    list of senseBoxes.
+  \item \code{plot.sensebox()}: Shows the spatial distribution of the given
+    list of senseBoxes on a map. Requires additional packages!
+  \item \code{\link{osem_phenomena}}: Get a named list with
+    counts of the measured phenomena of the given list of senseBoxes.
+}
 }
 
 \section{Retrieving measurements}{
 
-TODO
+Measurements can be retrieved through \code{\link{osem_measurements}} for a
+given phenomenon only. A subset of measurements may be selected by
+
+\itemize{
+  \item a list of senseBoxes, previously retrieved through
+    \code{\link{osem_box}} or \code{\link{osem_boxes}}.
+  \item a geographic bounding box, which can be generated with the
+    \code{\link{sf}} package.
+  \item a time frame
+  \item a exposure type of the given box
+}
+
+Data is returned as \code{data.frame} with the class \code{osem_measurements}.
+The provided columns may
 }
 
 \section{Retrieving statistics}{
 
-TODO
+Count statistics about the database are provided with \code{\link{osem_counts}}.
 }
 
-\section{Working with spatial data from openSenseMap}{
+\section{Integration with other packages}{
 
-TODO
-}
+The package aims to be compatible with the tidyverse.
+Helpers are implemented to ease the further usage of the retrieved data:
 
-\seealso{
-Useful links:
 \itemize{
-  \item \url{http://github.com/noerw/opensensmapR}
-  \item Report bugs at \url{http://github.com/noerw/opensensmapR/issues}
+  \item \code{\link{st_as_sf.sensebox}} & \code{\link{st_as_sf.osem_measurements}}:
+    Transform the senseBoxes or measurements into an \code{\link{sf}}
+    compatible format for spatial analysis.
+  \item \code{filter.sensebox()} & \code{mutate.sensebox()}: for use with
+    \code{\link{deplyr}}.
 }
+}
+
+\seealso{
+Report bugs at \url{https://github.com/noerw/opensensmapR/issues}
+
+openSenseMap API: \url{https://api.opensensemap.org/}
 
+official openSenseMap API documentation: \url{https://docs.opensensemap.org/}
 }
diff --git a/man/osem_box.Rd b/man/osem_box.Rd
index fd83544..cecb0ac 100644
--- a/man/osem_box.Rd
+++ b/man/osem_box.Rd
@@ -26,4 +26,6 @@ b = osem_box('593bcd656ccf3b0011791f5a')
 \href{https://docs.opensensemap.org/#api-Measurements-findAllBoxes}{openSenseMap API documentation (web)}
 
 \code{\link{osem_phenomena}}
+
+\code{\link{osem_boxes}}
 }
diff --git a/man/osem_boxes.Rd b/man/osem_boxes.Rd
index ebf8578..0286a04 100644
--- a/man/osem_boxes.Rd
+++ b/man/osem_boxes.Rd
@@ -53,4 +53,6 @@ b = osem_boxes(date = Sys.time(), phenomenon = 'PM2.5')
 \href{https://docs.opensensemap.org/#api-Measurements-findAllBoxes}{openSenseMap API documentation (web)}
 
 \code{\link{osem_phenomena}}
+
+\code{\link{osem_box}}
 }