Fixed README description and usage

README.md

@@ -1,8 +1,20 @@
-# Gdbm
+# GDBM
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/gdbm`. To experiment with that code, run `bin/console` for an interactive prompt.
+[![Build Status](https://travis-ci.org/ruby/gdbm.svg?branch=master)](https://travis-ci.org/ruby/gdbm)
 
-TODO: Delete this and the text above, and describe your gem
+GNU dbm is a library for simple databases. A database is a file that stores
+key-value pairs. Gdbm allows the user to store, retrieve, and delete data by
+key. It furthermore allows a non-sorted traversal of all key-value pairs.
+A gdbm database thus provides the same functionality as a hash. As
+with objects of the Hash class, elements can be accessed with <tt>[]</tt>.
+Furthermore, GDBM mixes in the Enumerable module, thus providing convenient
+methods such as #find, #collect, #map, etc.
+
+A process is allowed to open several different databases at the same time.
+A process can open a database as a "reader" or a "writer". Whereas a reader
+has only read-access to the database, a writer has read- and write-access.
+A database can be accessed either by any number of readers or by exactly one
+writer at the same time.
 
 ## Installation
 
@@ -22,13 +34,29 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
 
-## Development
+1. Opening/creating a database, and filling it with some entries:
+require 'gdbm'
+
+```ruby
+gdbm = GDBM.new("fruitstore.db")
+gdbm["ananas"]    = "3"
+gdbm["banana"]    = "8"
+gdbm["cranberry"] = "4909"
+gdbm.close
+```
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+2. Reading out a database:
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```ruby
+require 'gdbm'
+
+gdbm = GDBM.new("fruitstore.db")
+gdbm.each_pair do |key, value|
+  print "#{key}: #{value}\n"
+end
+gdbm.close
+```
 
 ## Contributing