Documentation not completely included in git repository

The projects documentation should be fully included in the git repository (and not hosted externally, e.g. in a Wiki).

As a user of the project I expect documentation to be distributed with it when cloning the repository.

## Advantages
- in the case of an offline situation (_rare_: no internet access, _more often_: highly secured secret offline nuclear-war-safe underground development facility in some mountains in Switzerland) the clone is still user-friendly, the documentation is available
- the included documentation is more likely to be up-to-date with the installed version of the project
- documentation does not rely on external service (wiki provider, web server, fair ISP, ...)
- code hosting solution can easily be switched (public -> private, git -> mercurial, ...)

## Disadvantages (if we are talking about wiki-vs-file)
- participation in documentation improvements are more difficult
- documentation improvements after specific project release are not distributed
- the repository size increases

I believe the advantages outweigh the disadvantages, and there is no extreme overhead in having BOTH an external documentation (e.g. Wiki) and documentation included in the project.

## Background and solution

Many projects provide two distinct kinds of documentation:
- documentation of the source code, which can be generated and explored using e.g. `rdoc`, `ri`, and other tools or online services
- higher-level documentation of use cases, general information about e.g. deployment, installation, common pitfalls, etc.
- example code that act as documentation without many words

While the former is usually contained in the respective source files (which are part of the gems distribution), the latter is often addressed in the projects README (or README.md, README.txt, ...), in separate human-readable "text" files (often in the `docs/` subdirectory) or on separate web pages like Wikis.

A simple solution would be to create fairly human-readable Markdown (`.md`) files in a subdirectory `doc`.

I'd be happy if you include this proposal and might help with a PR.

Documentation is important.