Documentation not included in gem

The gems documentation should be bundled with the gem (and not hosted externally, e.g. in a Wiki).

As a user of the gem I expect documentation to be distributed with it.

## 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 gem is still user-friendly, the documentation can be found in `~/.gems/`
- the bundled documentation is more likely to be up-to-date with the installed version of the gem
- 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 gem release are not distributed
- the distributed gems 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 gem.

## 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.

This gems development happens in a git repository and the gem is created from it via a `.gemspec` file and distributed e.g. via [rubygems.org](https://rubygems.org). A simple solution would be to create fairly human-readable Markdown (`.md`) files in a subdirectory `doc`. In some cases the `.gemspec` file has to be adjusted to include it.

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

Documentation is important.

Start by inspecting the gemspec, README, and any existing Wiki or documentation files mentioned in the issue. Check how the gem is built and which files are currently distributed. Done means the relevant higher-level documentation is included in the generated gem while any external documentation remains consistent.

Written by the indexing model from the issue text.