diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3060b08
--- /dev/null
+++ b/README.md
@@ -0,0 +1,23 @@
+Overview
+--------
+
+This library provides fast and reliably way to find visually similar images.
+
+Requirements
+------------
+
+Runtime:
+
+* libimagemagick / libgraphicsmagick (optional, may be disabled if no new samples needed)
+
+Compile-time:
+
+* headers for library above
+* C compiler with -std=c99 support
+* cmake >= 2.6
+
+See also
+--------
+
+* [build notes](docs/build.md)
+* [usage example](docs/usage.md)
diff --git a/docs/build.md b/docs/build.md
new file mode 100644
index 0000000..23a3d5e
--- /dev/null
+++ b/docs/build.md
@@ -0,0 +1,26 @@
+Build notes
+-----------
+
+General build flow as simple as this three commands:
+
+    cmake -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Release .
+    make
+    sudo checkinstall -- make install
+
+Now, cmake options explained:
+
+* `CMAKE_INSTALL_PREFIX` -- is root of place where to install the library
+* `CMAKE_BUILD_TYPE` -- tunes build options for warious presets (Release, Debug, ...)
+
+Project-specific options explained:
+
+* `SIMDB_SAMPLER` -- selects a library for use for making image samples. Now available:
+  * magick -- for this time is only production-ready sampler (both ImageMagick and GraphicsMagick supported)
+  * random -- backend for testing, generates sample with random data
+  * dummy -- empty backend, always fails (use only if you don't need to add new image samples)
+* `WITH_TOOLS` -- build some usefull tools
+  * simdb-tool -- manual manipulation of samples database
+  * simdb-upgrade -- upgrades database format to latest known version
+* `WITH_HARDENING` -- enable some additional compiler sanity checks
+
+`checkinstall` on last step is optional, but recommended tool, unless you don't care garbage in your system.
diff --git a/docs/usage.md b/docs/usage.md
new file mode 100644
index 0000000..d359a2e
--- /dev/null
+++ b/docs/usage.md
@@ -0,0 +1,72 @@
+Library usage
+-------------
+
+Database know nothing about location of the source images,
+records addressed only by some numeric id.
+
+Example usage:
+
+    #include <stdbool.h>
+    #include <stdio.h>
+    #include <stdlib.h>
+    #include <unistd.h>
+    
+    #include <simdb.h>
+    
+    int main() {
+      simdb_t *sdb = NULL;
+      simdb_search_t search;
+      simdb_match_t *match = NULL;
+      const char *path = "/tmp/test.sdb";
+      const char *files[] = {
+        "/path/to/file/a.jpg",
+        "/path/to/file/b.png",
+        "/path/to/file/c.bmp",
+      };
+      int ret = 0;
+    
+      if (!simdb_create(path)) {
+        perror("can't create test database");
+        return 1;
+      }
+    
+      sdb = simdb_open(path, SIMDB_FLAG_WRITE | SIMDB_FLAG_LOCKNB, &ret);
+      if (!sdb) {
+        fprintf(stderr, "can't open test simdb: %s\n", simdb_error(ret));
+        return 1;
+      }
+    
+      for (int i = 0; i < sizeof(files); i++) {
+        ret = simdb_record_add(sdb, i, files[i], 0);
+        if (ret < 0) {
+          fprintf(stderr, "can't add file from %s: %s\n", files[i], simdb_error(ret));
+        }
+      }
+    
+      simdb_search_init(&search);
+      /* tune search parameters */
+      search.d_ratio  = 0.1;  /* max difference in ratio -- 10% */
+      search.d_bitmap = 0.08; /* max difference in ratio --  8% */
+      /* compare given file against database */
+      const char *sample = "/path/to/file/d.png";
+      simdb_search_file(sdb, &search, sample);
+      /* show search results if any */
+      if (search.found) {
+        printf("file %s similar to:\n", sample);
+        for (int i = 0; i < search.found; i++) {
+          match = &search.matches[i];
+          printf("- %s (%d %%)\n", files[match->num], (int) match->d_bitmap * 100);
+        }
+        /* free search results */
+        simdb_search_free(&search);
+      }
+    
+      simdb_close(sdb);
+      unlink(path);
+    
+      return 0;
+    }
+
+You may build this example with next command:
+
+gcc -Wall -std=c99 -O0 -pedantic -lsimdb -o simdb-usage-test test.c