diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000000000000000000000000000000000000..4e373d433ecbb38cc8d5ac2a9a7b060e87addd15
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,151 @@
+.. _usage:
+
+Usage
+=====
+
+Django Pydenticon is targeted at developers who wish to integrate an identicon
+service in their Django projects. This chapter covers details on how an
+identicon image is served, and how to integrate Django Pydenticon with other
+applications.
+
+Requesting identicons
+---------------------
+
+Identicon images are served through specially formatted URL. Whenever such URL
+is submitted to Django Pydenticon application, an identicon image is created on
+the fly.
+
+The format of URL is ``/image/USER_DATA`` (relative to prefix URL assigned for
+the application), where **USER_DATA** can be either in hashed or raw format. For
+example, if Django Pydenticon application is reachable under ``/identicon/``,
+identicon images can be requested using the following URLs:
+
+* ``/identicon/image/somedataforhashing`` (raw data)
+* ``/identicon/image/55d207ea47247b375dc1f495517f1332`` (pre-hashed data using
+ *md5*)
+
+.. warning::
+ Keep in mind that if user data is submitted in pre-hashed form, the digest
+ used should match with the digest configured for Django Pydenticon
+ application. If digest does not match, the user data will be treated as any
+ other user data, and it will be hashed once again.
+
+URL instance namespaces
+-----------------------
+
+When resolving Django Pydenticon URLs, you should always use the URL names in
+conjunction with application instance namespace.
+
+Default application instance namespace is ``django_pydenticon``. Alternative
+instance namespace can be specified by passing an (optional) argument to
+``django_pydenticons.urls.get_patterns`` function.
+
+For example, if default namespace is in use, the ``image`` URL would be
+referenced as ``django_pydenticon:image`` in template tag ``url`` or function
+call ``reverse``.
+
+Generating identicon URLs in templates
+--------------------------------------
+
+If the data (whether raw or hashed) is available in template's context, an
+identicon URL can be easily generated from within the template itself. This can
+be achieved via ``url`` tag.
+
+The URL for serving the identicons is named ``image``. It should always be
+referenced in conjunction with an application instance namespace. The
+application namespace defaults to ``django_pydenticon``, unless custom instance
+namespace is passed when including the application URLs via
+``django_pydenticon.urls.get_patterns``. In case of default namespace, that
+means the URL would be referenced to as ``django_pydenticon:image``.
+
+For example, let's say that it's necessary to show an identicon based on
+username next to every comment. Related template snippet could look something
+similar to the following::
+
+
+ {% for comment in comments %}
+ - {{ comment.text }}
+ {% endfor %}
+
+
+Generating identicon URLs programatically
+-----------------------------------------
+
+The URLs can be generated programtically, using Python code. Afterwards those
+URLs can be either passed into template's rendering context, or used inside of
+code for whatever other purposes. This is achieved by using the ``reverse`` URL
+resolver (from ``django.core.urlresolvers``).
+
+The URL for serving the identicons is named ``image``. It should always be
+referenced in conjunction with an application instance namespace. The
+application namespace defaults to ``django_pydenticon``, unless custom instance
+namespace is passed when including the application URLs via
+``django_pydenticon.urls.get_patterns``. In case of default namespace, that
+means the URL would be referenced to as ``django_pydenticon:image``.
+
+For example, let's say that it's necessary to show an identicon based on
+username next to every comment. A special context variable could be passed into
+template that would contain a list of comments, where each comment consists out
+of identicon URL and comment itself. The Python code could look something
+similar to::
+
+ comments_context = []
+
+ for comment in comments:
+ identicon_url = reverse("django_pydenticon:image",
+ kwargs={"data": comment.user.username})
+ comments_context.append({"text": comment.text,
+ "identicon_url": identicon_url})
+
+ return render_to_response('myapp/comments.html',
+ {"comments": comments_context})
+
+With the above context set-up, the ``myapp/comments.html`` template could
+contain a snippet similar to::
+
+
+ {% for comment in comments %}
+ - {{ comment.text }}
+ {% endfor %}
+
+
+Overriding identicon parameters
+-------------------------------
+
+By default, the identicon generator will use parameters from project settings
+for each request, falling back to application defaults if none were defined. In
+addition to this static configuration, some parameters can be overridden per
+request.
+
+Per-request identicon generator parameters are passed via *GET* parameters. The
+following *GET* parameters are available:
+
+w
+ Specifies the width of generated identicon image in pixels. Overrides the
+ ``PYDENTICON_WIDTH`` configuration option.
+
+h
+ Specifies the height of generated identicon image in pixels. Overrides the
+ ``PYDENTICON_HEIGHT`` configuration option.
+
+f
+ Specifies the format of generated identicon. Overrides the
+ ``PYDENTICON_FORMAT`` configuration option.
+
+p
+ Specifies the padding that will be added to the generated identicon image. The
+ value should be provided as 4 comma-separated positive integers.
+
+i
+ Specifies whether the background and foreground colour in generated identicon
+ should be inverted (swapped) or not. The value passed for this parameter
+ should be ``true`` or ``false``.
+
+Passing an invalid parameter value via *GET* parameter will result in a
+``SuspiciousOperation`` exception being raised.
+
+For example, the following request would generate an identicon with width of
+``320``, height of ``240``, format ``PNG``, padding (top, bottom, left, right)
+of ``10, 10, 20, 20``, and with inverted foreground and background colours::
+
+ /identicon/image/somedata?w=320&h=240&f=png&p=10,10,20,20&i=true