diff --git a/CHANGELOG.md b/CHANGELOG.md
index d223e23..96a6ae5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,5 +4,9 @@ All user visible changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/), as described
 for Rust libraries in [RFC #1105](https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md)
 
+## 0.1.1 : 2017-11-06 : First words
+* Describe the basic building blocks (traits) defined in this crate.<br/>
+  (documentation only, no code changes)
+
 ## 0.1.0 : 2017-10-26 : Newborn
 First release
diff --git a/README.md b/README.md
index bc3e14d..505b8a3 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,80 @@ types for modelling the domain of genetic algorithms.
 
 [Documentation](https://docs.rs/genevo)
 
+## Features
+
+This crate provides a default implementation of the genetic algorithm to be used
+to find solutions for a wide variety of search and optimization problems.
+
+The implementation is split into building blocks which are all represented by
+traits. This crate provides most common implementation for all building blocks.
+So it can be used for many problems out of the box.
+
+Anyway if one wants to use different implementations for one or the other
+building block it can be extended by implementing any of the traits in a more
+sophisticated and customized way.
+
+The building blocks (or traits) are:
+* Simulation
+* Algorithm
+* Termination
+* Operator
+* Population
+* Phenotype and Genotype
+* FitnessFunction
+
+The simulation can run an algorithm that is executed in a loop. An algorithm
+implements the steps to be done for each iteration of the loop. The provided
+implementation of the genetic algorithm implements the `Algorithm` trait and
+can therefore be executed by the `Simulator` which is the provided
+implementation of the `Simulation` trait.
+
+The `Simulator` holds state about the simulation and tracks statistics about
+the execution of the algorithm, such as number of iterations and processing
+time.
+
+The simulation runs until the termination criteria are met. The termination
+criteria can be a single one such as max number of iterations or a logical
+combination of multiple termination criteria, e.g. max number of iterations
+OR a minimum fitness value has been reached. Of coarse `Termination` is a 
+trait as well and one can implement any termination criteria he/she can think
+of.
+
+The algorithm can make use of operators that perform different stages of the
+algorithm. E.g. the basic genetic algorithm defines the stages: selection,
+crossover, mutation and accepting. These stages are performed by the appropriate
+operators: `SelectionOp`, `CrossoverOp`, `MutationOp`, `RecombinationOp` and
+`ReinsertionOp`.
+
+This crate provides multiple implementations for each one of those operators.
+So one can experiment with combining the different implementations to compose
+the best algorithm for a specific search or optimization problem. Now you may
+have guessed that the defined operators are traits as well and you are free
+to implement any of these operators in a way that suits best for your problem
+and plug them into the provided implementation of the genetic algorithm.
+
+The genetic algorithm needs a population that it evolves with each iteration.
+One population represents a possible candidate solution for an optimization
+problem for which the best solution is search for. This crate provides a
+`PopulationBuilder` to build population of genomes. To run the population
+builder it needs an implementation of the `GenomeBuilder` trait. A
+`GenomeBuilder` defines how to create one individual (or genome) within the
+population.
+
+Last but maybe most important are the traits `Phenotype`, `Genotype` and
+`FitnessFunction`. These are the traits which define the domain of the
+optimization problem. They must be implemented individually for each application
+of the genetic algorithm.
+
+Enough words about the building blocks. Show me some concrete examples. Have
+a look at the examples in the examples folder to find out how to use this crate:
+
+* [monkeys](./examples/monkeys/main.rs): explores the idea of Shakespeare's monkeys, also known
+  as the [infinite monkey theorem](https://en.wikipedia.org/wiki/Infinite_monkey_theorem)
+* [queens](./examples/queens/main.rs): searches for solutions of the
+  [N Queens Problem](https://en.wikipedia.org/wiki/Eight_queens_puzzle)
+
+
 ## Usage
 
 Add this to your `Cargo.toml`:
@@ -54,13 +128,11 @@ And add this to your crate:
 extern crate genevo;
 ```
 
-Have a look at the examples to see how to use this crate:
-* [monkeys](./examples/monkeys/main.rs): explores the idea of Shakespeare's monkeys, also known
-  as the [infinite monkey theorem](https://en.wikipedia.org/wiki/Infinite_monkey_theorem)
-* [queens](./examples/queens/main.rs): searches for solutions of the
-  [N Queens Problem](https://en.wikipedia.org/wiki/Eight_queens_puzzle)
+## References
 
-## Research
+I started this project mainly to learn about genetic algorithms (GAs). During
+this journey I searched a lot for information about GA. Here are the links to
+sources of information about GA that I found most useful for me. 
 
 [[JFGA]]: Jeremy Fisher: Genetic Algorithms
 
diff --git a/src/lib.rs b/src/lib.rs
index 6736126..93df835 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -3,17 +3,76 @@
 //! `genevo` is a library for implementing and executing simulations of
 //! optimization and search problems using a genetic algorithm (GA).
 //!
-//! ## Installation
+//! It provides a default implementation of the genetic algorithm to be used
+//! to find solutions for a wide variety of search and optimization problems.
 //!
-//! You can use this library by adding the following lines to your `Cargo.toml`
-//! file:
+//! The implementation is split into building blocks which are all represented by
+//! traits. This crate provides most common implementation for all building blocks.
+//! So it can be used for many problems out of the box.
 //!
-//! ```ignore
-//! [dependencies]
-//! genevo = "0.1"
-//! ```
+//! Anyway if one wants to use a different implementation for one or the other
+//! building block it can be extended by implementing any of the traits in a more
+//! sophisticated and customized way.
 //!
-//! and adding `extern crate genevo;` to your crate root.
+//! The building blocks (or traits) are:
+//! * Simulation
+//! * Algorithm
+//! * Termination
+//! * Operator
+//! * Population
+//! * Phenotype and Genotype
+//! * FitnessFunction
+//!
+//! The simulation can run an algorithm that is executed in a loop. An algorithm
+//! implements the steps to be done for each iteration of the loop. The provided
+//! implementation of the genetic algorithm implements the `Algorithm` trait and
+//! can therefore be executed by the `Simulator` which is the provided
+//! implementation of the `Simulation` trait.
+//!
+//! The `Simulator` holds state about the simulation and tracks statistics about
+//! the execution of the algorithm, such as number of iterations and processing
+//! time.
+//!
+//! The simulation runs until the termination criteria are met. The termination
+//! criteria can be a single one such as max number of iterations or a logical
+//! combination of multiple termination criteria, e.g. max number of iterations
+//! OR a minimum fitness value has been reached. Of coarse `Termination` is a
+//! trait as well and one can implement any termination criteria he/she can think
+//! of.
+//!
+//! The algorithm can make use of operators that perform different stages of the
+//! algorithm. E.g. the basic genetic algorithm defines the stages: selection,
+//! crossover, mutation and accepting. These stages are performed by the appropriate
+//! operators: `SelectionOp`, `CrossoverOp`, `MutationOp`, `RecombinationOp` and
+//! `ReinsertionOp`.
+//!
+//! This crate provides multiple implementations for each one of those operators.
+//! So one can experiment with combining the different implementations to compose
+//! the best algorithm for a specific search or optimization problem. Now you may
+//! have guessed that the defined operators are traits as well and you are free
+//! to implement any of these operators in a way that suits best for your problem
+//! and plug them into the provided implementation of the genetic algorithm.
+//!
+//! The genetic algorithm needs a population that it evolves with each iteration.
+//! One population represents a possible candidate solution for an optimization
+//! problem for which the best solution is search for. This crate provides a
+//! `PopulationBuilder` to build population of genomes. To run the population
+//! builder it needs an implementation of the `GenomeBuilder` trait. A
+//! `GenomeBuilder` defines how to create one individual (or genome) within the
+//! population.
+//!
+//! Last but maybe most important are the traits `Phenotype`, `Genotype` and
+//! `FitnessFunction`. These are the traits which define the domain of the
+//! optimization problem. They must be implemented individually for each application
+//! of the genetic algorithm.
+//!
+//! Enough words about the building blocks. Show me some concrete examples. Have
+//! a look at the examples in the examples folder to find out how to use this crate:
+//!
+//! * [monkeys](./examples/monkeys/main.rs): explores the idea of Shakespeare's monkeys, also known
+//!   as the [infinite monkey theorem](https://en.wikipedia.org/wiki/Infinite_monkey_theorem)
+//! * [queens](./examples/queens/main.rs): searches for solutions of the
+//!   [N Queens Problem](https://en.wikipedia.org/wiki/Eight_queens_puzzle)
 
 #![warn(
     missing_copy_implementations,