diff --git a/doc/doxygen/src/mainpage.md b/doc/doxygen/src/mainpage.md
index 488c280e46cd43979ebdb687003b051f3b61aac6..a0331f2390b10e0d7c4644cc3173a04e7f035232 100644
--- a/doc/doxygen/src/mainpage.md
+++ b/doc/doxygen/src/mainpage.md
@@ -3,273 +3,243 @@ RIOT Documentation {#mainpage}
[TOC]
-Overview
-========
-
-RIOT is an operating system designed for the particular requirements of Internet
-of Things (IoT) scenarios. These requirements comprise a low memory footprint,
-high energy efficiency, real-time capabilities, a modular and configurable
-communication stack, and support for a wide range of low-power devices. RIOT
-provides a microkernel, utilities like cryptographic libraries, data structures
-(bloom filters, hash tables, priority queues), or a shell, different network
-stacks, and support for various microcontrollers, radio drivers, sensors, and
-configurations for entire platforms, e.g. Zolertia Z1 or STM32 Discovery
-Boards.
-
-The microkernel itself comprises thread management, a priority-based scheduler,
-a powerful API for inter-process communication (IPC), a system timer, and
-mutexes.
-
-In order to build an application or library with RIOT, you need first to
-download the source code ([Getting the source
-code](https://github.com/RIOT-OS/RIOT/wiki/Introduction#wiki-getting-the-source-code)). This contains - besides the
-before mentioned features - also some example applications (located in the
-`examples` subdirectory) and a sample Makefile you may use for your own
-project. This Makefile template shows you how to compile and link your application
-against RIOT ([Compiling RIOT](https://github.com/RIOT-OS/RIOT/wiki/Introduction#wiki-compiling-riot)).
-
-If you want to use RIOT directly with your embedded platform, you need to
-install the corresponding toolchain for the deployed microcontroller ([ARM
-based platforms](https://github.com/RIOT-OS/RIOT/wiki/Introduction#wiki-platforms-based-on-arm), [TI MSP430 based
-platforms](https://github.com/RIOT-OS/RIOT/wiki/Introduction#wiki-platforms-based-on-ti-msp430)).
-
-### Native RIOT - Run RIOT on your PC!
-
-As a special platform, you will find a CPU and board called `native` in the
-repository. This target allows you to run RIOT as a process on Linux on most
-supported hardware platforms. Just set `BOARD = native` in your
-application's Makefile, call `make`, and execute the resulting elf-file. Further
-documentation about the native port can be found in `cpu/native/README.md`.
-
-Structure
----------
-
-
-
-The RIOT repository contains the following ten subdirectories:
- * boards
- * core
- * cpu
- * dist
- * doc
- * drivers
- * examples
- * pkg
- * sys
- * tests
-
-The `boards` directory provides the configurations and initialization code for
-supported IoT platforms. In `core` you can find the kernel, while `cpu`
-comprises microcontroller specific implementations like startup and exception
-handling code. The directory `dist` contains a template for an application's Makefile
-and external utilities like the terminal program `pyterm` or a script to build
-your own toolchain for ARM microcontrollers. Not very surprisingly you will find
-the (doxygen) documentation in `doc` and peripheral driver code in `drivers`.
-The `examples` directory provides some exemplary applications, `pkg` includes
-Makefiles to integrate external libraries into RIOT, and `sys` system libraries
-as well as the implementation of the network stacks which are located in
-`sys/net`. Finally, the subdirectory `tests` contains test applications,
-including also a few expect scripts to automatically validate some of them.
-
-~~~~~~~~{.c}
-int main()
-{
- puts("Hello World!");
- return 0;
-}
-~~~~~~~~
-
-Getting the source code
------------------------
-
-You can obtain the latest RIOT code from our [Github](https://github.com/RIOT-OS/)
-repository either by [downloading the latest tarball](https://github.com/RIOT-OS/RIOT/releases)
-or by cloning the [git repository](https://github.com/RIOT-OS/RIOT).
-
-In order to clone the RIOT repository, you need the [Git revision control
-system](http://git-scm.com/) and run the following command:
-
-~~~~~~~~{.sh}
-git clone git://github.com/RIOT-OS/RIOT.git
-~~~~~~~~
-
-The repository contains the kernel, support for different CPUs and platforms, device
-drivers, system libraries, and network stack implementations. Inaddition it comprises
-various example applications to demonstrate the usage ofsome important features.
-
-It also provides you with useful tools like a terminal program and scripts to
-setup a toolchain.
-
-Compiling RIOT
---------------
-Depending on the hardware you want to use, you need to first install a
-corresponding toolchain:
-
-* [ARM-based platforms](https://github.com/RIOT-OS/RIOT/wiki/Family:-ARM)
-* [TI MSP430](https://github.com/RIOT-OS/RIOT/wiki/Family:-MSP430)
-* [Atmel ATmega](https://github.com/RIOT-OS/RIOT/wiki/Family%3A-ATmega)
-* [native](https://github.com/RIOT-OS/RIOT/wiki/Family:-native)
-
-### Create an application
-Once you have set up the toolchain, you can create your own application. Apart from
-the C file(s) containing your source code you need a Makefile. A template
-Makefile is available in the `dist` folder of the
-[RIOT repository](https://github.com/RIOT-OS/RIOT).
-
-Within your application's Makefile, you can define the target hardware as well as
-the modules you want to use.
-
-Unless specified otherwise, make will create an elf-file as well as an Intel
-hex file in the `bin` folder of your application directory.
-
-Special features
-================
-
-The build system
-----------------
-
-RIOT uses GNU make as build system. The simplest way to compile and link an
-application (or library) with RIOT, is to set up a Makefile providing
-at least the following variables:
-
- * `APPLICATION`: should contain the (unique) name of your application
- * `BOARD`: specifies the platform the application should be build for by default
- * `RIOTBASE`: specifies the path to your copy of the RIOT repository
- (note, that you may want to use `$(CURDIR)` here, to give a relative path)
-
-Additionally it has to include the `Makefile.include`, located in RIOT's root
-directory. You can use Make's `?=` operator in order to allow overwriting
-variables from the command line. For example, you can easily specify the target
-platform, using the sample Makefile, by invoking make like this:
-
-~~~~~~~~{.sh}
-make BOARD=iotlab-m3
-~~~~~~~~
-
-Besides typical targets like `clean`, `all`, or `doc`, RIOT provides the special
-targets `flash` and `term` to invoke the configured flashing and terminal tools
-for the specified platform. These targets use the variable `PORT` for the serial
-communication to the device. Neither this variable nor the targets `flash` and
-`term` are mandatory for the native port.
-
-For the native port, `PORT` has a special meaning: it is used to identify the tap
-interface if the @ref netdev2_tap module is used. The target `debug` can be used
-to invoke a debugger on some platforms. For the native port the additional targets
-such as `all-valgrind` and `valgrind` exist. Refer to `cpu/native/README.md` for
-additional information
-
-Some RIOT directories contain special Makefiles like `Makefile.base`,
-`Makefile.include` or `Makefile.dep`. The first one can be included into other
-Makefiles to define some standard targets. The files called `Makefile.include`
-are used in `boards` and `cpu` to append target specific information to
-variables like `INCLUDES`, setting the include paths. `Makefile.dep` serves to
-define dependencies.
-
-Learn more about the build system in the
-[Wiki](https://github.com/RIOT-OS/RIOT/wiki/The-Make-Build-System)
-
-Including modules
------------------
-
-By default a RIOT application comprises only the applications' code itself, the kernel,
-and platform specific code. In order to use additional modules, such as a
-particular device driver or a system library, you have to append the modules'
-names to the USEMODULE variable. For example, to build an application using the SHT11
-temperature sensor and UDP/IPv6 network stack, your Makefile needs to contain
-these lines:
-
-~~~~~~~~{.mk}
-USEMODULE += sht11
-USEMODULE += gnrc_ipv6_default
-USEMODULE += gnrc_udp
-~~~~~~~~
-
-To contribute a new module to RIOT, your module's Makefile needs to set the
-variable `MODULE` to a unique name. If the module depends on other modules, this
-information needs to be added to RIOT's `Makefile.dep`.
-
-The main function
------------------
-
-After the board is initialized, RIOT starts two threads: the idle thread and the
-main thread. The idle thread has the lowest priority and will run, whenever no
-other thread is ready to run. It will automatically use the lowest possible
-power mode for the device. The main thread - configured with a default priority
-that is right in the middle between the lowest and the highest available
-priority - is the first thread that runs and calls the main function. This
-function needs to be defined by the application.
-
-Choosing the right stack size
------------------------------
-
-Choosing the right stack size for a new thread is not an easy, but a very
-crucial task. Since memory is usually a scarce resource in IoT scenarios,
-one must be careful not to assign too much stack to a single thread.
-However, if you allocate too little memory for a stack, your application
-will probably crash. The minimum stack size depends also on some RIOT
-internal structs and is hardware dependent. In order to help developers
-finding the right stack size, RIOT defines some typical stack sizes in
-`cpu_conf.h` (which should be provided by the implementation for all
-supported MCUs). The constants for these stack sizes are
-
-* `THREAD_STACKSIZE_IDLE`
-* `THREAD_STACKSIZE_DEFAULT`
-* `THREAD_EXTRA_STACKSIZE_PRINTF`
-* `THREAD_STACKSIZE_MAIN`
-
-and can be used by including `kernel.h`. ARM based platforms additionally
-define `THREAD_EXTRA_STACKSIZE_PRINTF_FLOAT`, because newlib's `printf`
-implementation uses more memory for printing floating point numbers.
-
-`THREAD_STACKSIZE_IDLE` is the stack size for the idle thread and
-probably the smallest sensible stack size. `THREAD_STACKSIZE_DEFAULT`
-is a default size for any typical thread, *not* using `printf`.
-`THREAD_EXTRA_STACKSIZE_PRINTF` defines additional stack space needed if the
-thread needs to call printf (which requires additional memory when using
-newlib). `THREAD_STACKSIZE_MAIN` is the stack size for the main thread
-and probably a good size for your application. (Note, that on most
-non-newlib dependent platforms this will probably equal
-`THREAD_STACKSIZE_DEFAULT`.)
-
-The IPC
--------
+RIOT in a nutshell {#riot-in-a-nutshell}
+==================
+RIOT is an open-source microkernel-based operating system, designed to match
+the requirements of Internet of Things (IoT) devices and other embedded
+devices. These requirements include a very low memory footprint (on the order
+of a few kilobytes), high energy efficiency, real-time capabilities,
+communication stacks for both wireless and wired networks, and support for a
+wide range of low-power hardware.
+
+RIOT provides a microkernel, multiple network stacks, and utilities which
+include cryptographic libraries, data structures (bloom filters, hash tables,
+priority queues), a shell and more. RIOT supports a wide range of
+microcontroller architectures, radio drivers, sensors, and configurations for
+entire platforms, e.g. Atmel SAM R21 Xplained Pro, Zolertia Z1, STM32 Discovery
+Boards etc. (see the list of
+[supported hardware](https://github.com/RIOT-OS/RIOT/wiki/RIOT-Platforms).
+Across all supported hardware (32-bit, 16-bit, and 8-bit platforms). RIOT
+provides a consistent API and enables ANSI C and C++ application programming,
+with multithreading, IPC, system timers, mutexes etc.
+
+Contribute to RIOT {#contribute-to-riot}
+==================
+RIOT is developed by an open community that anyone is welcome to join:
+ - Download and contribute your code on
+ [GitHub](https://github.com/RIOT-OS/RIOT). You can read about how to
+ contribute [in our GitHub
+ Wiki](https://github.com/RIOT-OS/RIOT/wiki/Contributing-to-RIOT).
+ - [Subscribe](http://lists.riot-os.org/mailman/listinfo/users) to
+ users@riot-os.org to ask for help using RIOT or writing an application for
+ RIOT (or to just stay in the loop). A searchable archive of this list is
+ available at the
+ [RIOT user Gmane newsgroup](http://news.gmane.org/gmane.os.riot.user)
+ - [Subscribe]((http://lists.riot-os.org/mailman/listinfo/devel) to
+ devel@riot-os.org to follow and discuss kernel and network stack
+ developement, or hardware support. A searchable archive of this list is
+ available at the
+ [RIOT devel Gmane newsgroup](http://news.gmane.org/gmane.os.riot.devel)
+ - Follow us on [Twitter](https://twitter.com/RIOT_OS) for news from the RIOT
+ community.
+ - Contact us on IRC for live support and discussions:
+ [irc.freenode.org #riot-os](irc://irc.freenode.org/riot-os)
+
+
+The quickest start {#the-quickest-start}
+==================
+You can run RIOT on most IoT devices, on open-access testbed hardware (e.g.
+IoT-lab), and also directly as a process on your Linux/FreeBSD/OSX machine (we
+call this the `native` port). Try it right now in your terminal window:
+
+~~~~~~~{.sh}
+git clone git://github.com/RIOT-OS/RIOT.git # assumption: git is pre-installed
+git checkout <LATEST_RELEASE>
+cd RIOT
+./dist/tools//tapsetup/tapsetup # create virtual Ethernet
+ # interfaces to connect to RIOT
+cd examples/default/
+make all
+make term
+~~~~~~~
+
+... and you are in the RIOT shell!
+Type `help` to discover available commands. For further information see the
+[README of the `default` example](https://github.com/RIOT-OS/RIOT/tree/).
+
+To use RIOT directly on your embedded platform, and for more hands-on details
+with RIOT, see [TODO: link to getting started guide].
+
+Before that, skimming through the next section is recommended (but not
+mandatory).
+
+Structure {#structure}
+=========
-Like any microkernel system, RIOT has an IPC API that enables data exchange
-between modules or a single module and the kernel. This API is documented in
-@ref core_msg. The IPC can be used in several ways, such as synchronous or
-asynchronous, blocking or non-blocking, with or without a message queue. In
-the default case, a thread does not have a message queue. Hence, messages
-sent in a non-blocking manner are lost, when the target thread is not in
-receive mode. A thread may set up a message queue using the msg_init_queue()
-function, but has to provide the memory for this queue itself.
+This section walks you through RIOT's structure. Once you understand this
+structure, you will easily find your way around in RIOT's code base.
+
+RIOT's code base is structured into five groups.
+
+<!-- TODO: add graphic -->
+
+ - The kernel (`core`)
+ - Platform specific code (`cpu`; `boards`)
+ - Device drivers (`drivers`)
+ - Libraries and network code (`sys`; `pkg`)
+ - Applications for demonstrating features and for testing (`examples`;
+ `tests`)
+
+In addition RIOT includes a collection of scripts for various tasks (`dist`) as
+well as a predefined environment for generating this documentation (`doc`).
+
+The structural groups are projected onto the directory structure of RIOT, where
+each of these groups resides in one or two directories in the main RIOT
+directory.
+
+The following list gives a more detailed description of each of RIOT's
+top-level directories:
+
+core
+----
+This directory contains the actual kernel. The kernel consists of the
+scheduler, inter-process-communication (messaging), threading, thread
+synchronization, and supporting data-structures and type definitions.
+
+See @ref core for further information and API documentations.
+
+boards
+------
+The platform dependent code is split into two logic elements: CPUs and boards,
+while maintaining a strict 1-to-n relationship, a board has exactly one CPU,
+while a CPU can be part of n boards. The CPU part contains all generic, CPU
+specific code (see below).
+
+The board part contains the specific configuration for the CPU it contains.
+This configuration mainly includes the peripheral configuration and
+pin-mapping, the configuration of on-board devices, and the CPU's clock
+configuration.
+
+On top of the source and header files needed for each board, this directory
+additionally may include some script and configuration files needed for
+interfacing with the board. These are typically custom flash/debug scripts or
+e.g. OpenOCD configuration files. For most boards, these files are located in a
+`dist` sub-directory of the board.
+
+See here @ref boards for further information.
+
+cpu
+---
+For each supported CPU this directory contains a sub-directory with the name of
+the CPU. These directories then contain all CPU specific configurations, such
+as implementations of power management (LPM), interrupt handling and vectors,
+startup code, clock initialization code and thread handling (e.g. context
+switching) code. For most CPUs you will also find the linker scripts in the
+`ldscripts` sub-directory.
+
+In the `periph` sub-directory of each CPU you can find the implementations of
+the CPU's peripheral drivers like SPI, UART, GPIO, etc. See @ref driver_periph
+for their API documentation.
+
+Many CPUs share a certain amount of their code (e.g. all ARM Cortex-M based
+CPUs share the same code for task switching and interrupt handling). This
+shared code is put in its own directories, following a `xxxxx_common` naming
+scheme. Examples for this is code shared across architectures (e.g.
+`cortexm_common`, `msp430_comon`) or code shared among vendors (e.g.
+`kinetis_common`).
+
+See @ref cpu for more detailed informtation.
+
+drivers
+-------
+This directory contains the drivers for external devices such as network
+interfaces, sensors and actuators. Each device driver is put into its own
+sub-directory with the name of that device.
-Auto-inititialization
----------------------
+All of RIOT's device drivers are based on the peripheral driver API (e.g. SPI,
+GPIO, etc.) and other RIOT modules like the `xtimer`. This way the drivers are
+completely platform agnostic and they don't have any dependencies into the CPU
+and board code.
-Most modules require initialization before they can be used. In some cases the
-initialization function does not require a parameter. For these modules the
-@ref sys_autoinit feature is included automatically. It calls all module
-initialization functions with a `void` parameter just before the main thread
-gets executed. You can deactivate this behavior (e.g. for testing) by adding
-the line
+See @ref drivers for more details.
-~~~~~~~~{.mk}
-DISABLE_MODULE += auto_init
-~~~~~~~~
+sys
+---
+RIOT follows the micro-kernel design paradigm where everything is supposed to
+be a module. All of these modules that are not part of the hardware abstraction
+nor device drivers can be found in this directory. The libraries include data
+structures (e.g. bloom, color), crypto libraries (e.g. hashes, AES) ,
+high-level APIs (e.g. Posix implementations), memory management (e.g. malloc),
+the RIOT shell and many more.
-to your Makefile.
+See @ref sys for a complete list of available libraries
-Networking
+sys/net
+-------
+The `sys/net` sub-directory needs to be explicitly mentioned, as this is where
+all the networking code in RIOT resides. Here you can find the network stack
+implementations (e.g. the GNRC stack) as well as network stack agnostic code as
+header definitions or network types.
+
+See @ref net for more details on networking code.
+
+pkg
+---
+RIOT comes with support for a number of external libraries (e.g.
+[OpenWSN](http://www.openwsn.org/),
+[microcoap](https://github.com/1248/microcoap)). The way they are included is
+that RIOT ships with a custom Makefile for each supported library that
+downloads the library and optionally applies a number of patches to make it
+work with RIOT. These Makefiles and patches can be found in the `pkg`
+directory.
+
+See @ref pkg for a detailed description on how this works.
+
+examples
+--------
+Here you find a number of example applications that demonstrate certain
+features of RIOT. The default example found in this directory is a good
+starting point for anyone who is new to RIOT.
+
+For more information best browse that directory and have a look at the
+`README.md` files that ship with each example.
+
+tests
+-----
+Many features/modules in RIOT come with their own test application, which are
+located in this directory. In contrary to the examples these tests are mostly
+focusing on a single aspect than on a set of features. Despite for testing, you
+might consider these tests also for insights on understanding RIOT.
+
+dist & doc
----------
-@todo
-
-Community
-=========
-
-Whether you are looking for help with writing an application for RIOT, want to
-learn more about it, or just stay in the loop you are invited to join the
-[RIOT-users mailing list](http://lists.riot-os.org/mailman/listinfo/users).
-For developers who want to participate and contribute to the kernel development
-or integrate new MCU and platform support the
-[RIOT-devel mailing list](http://lists.riot-os.org/mailman/listinfo/devel) is
-the right place.
+All the tooling around RIOT can be found in these two folders.
+
+`doc` contains the doxygen configuration and also contains the compiled doxygen
+output after running `make doc`.
+
+Lastly, the `dist` directory contains tools to help you with RIOT. These
+include
+the serial terminal application `pyterm`, generic scripts for flashing,
+debugging, reseting (e.g. support for [OpenOCD](http://openocd.org/),
+[Jlink](https://www.segger.com/jlink_base.html)), as well as code enabling easy
+integration to open testbeds such as the [IoT-LAB](https://www.iot-lab.info/).
+Furthermore you can find here scripts to do all kind of code and style checks.
+
+<!--
+Further information {#further-information}
+===================
+*TBD*
+
+Idea for this section: just name each of RIOT's main features/concepts and link
+to an appropriate page with further information:
+ - Create an application
+ - Networking
+ - The `main()` function
+ - Make system
+ - Include modules
+ - Threading
+ - Choose the right stack size
+ - IPC
+ - Auto initialization
+-->