diff --git a/github-activity-widget/README.md b/github-activity-widget/README.md
index b99e7b1..8a7fe09 100644
--- a/github-activity-widget/README.md
+++ b/github-activity-widget/README.md
@@ -1,3 +1,63 @@
 # GitHub Activity Widget
 
-WIP
\ No newline at end of file
+Widget shows recent activities on GitHub. It is very similar to the GitHub's "All activity" feed on the main page:
+
+![screenshot](./screenshot.png)
+
+Mouse click on the item opens repo/issue/pr depending on the type of the activity. Mouse click on user's avatar opens user GitHub profile.
+
+## Customization
+
+It is possible to customize widget by providing a table with all or some of the following config parameters:
+
+| Name | Default | Description |
+|---|---|---|
+| `icon` | github.png from the widget sources | Widget icon displayed on the wibar |
+| `username` | your username | Required parameter |
+| `number_of_events` | 10 | Number of events to display in the list |
+
+## How it works
+
+Everything starts with this timer, which gets recent activities by calling GitHub [Events API](https://developer.github.com/v3/activity/events/) and stores the response under /.cache/awmw/github-activity-widget/activity.json directory:
+
+```lua
+gears.timer {
+    timeout   = 600,   -- calls every ten minutes
+    call_now  = true,
+    autostart = true,
+    callback  = function()
+        spawn.easy_async(string.format(UPDATE_EVENTS_CMD, username, CACHE_DIR), function(stdout, stderr)
+            if stderr ~= '' then show_warning(stderr) return end
+        end)
+    end
+}
+```
+
+There are several reasons to store output in a file and then use it as a source to build the widget, instead of calling it everytime the widget is opened: 
+ - activity feed does not update that often
+ - events API doesn't provide filtering of fields, so the output is quite large (300 events)
+ - it's much faster to read file from filesystem
+
+ Next important part is **rebuild_widget** function, which is called when mouse button clicks on the widget on the wibar. It receives a json string which contains first n events from the cache file. Those events are processed by `jq` (get first n events, remove unused fields, slightly change the json structure to simplify serialization to lua table). And then it builds a widget, row by row in a loop. To display the text part of the row we already have all neccessary information in the json string which was converted to lua table. But to show an avatar we should download it first. This is done in the following snippet. First it creates a template and then checks if file already exists, and sets it in template, otherwise, downloads it asynchronously and only then sets in:
+
+ ```lua
+local avatar_img = wibox.widget {
+    resize = true,
+    forced_width = 40,
+    forced_height = 40,
+    widget = wibox.widget.imagebox
+}
+
+if gfs.file_readable(path_to_avatar) then
+    avatar_img:set_image(path_to_avatar)
+else
+    -- download it first
+    spawn.easy_async(string.format(
+            DOWNLOAD_AVATAR_CMD,
+            CACHE_DIR,
+            event.actor.id,
+            event.actor.avatar_url), 
+            -- and then set
+            function() avatar_img:set_image(path_to_avatar) end)
+end
+ ```
\ No newline at end of file
diff --git a/github-activity-widget/github-activity-widget.lua b/github-activity-widget/github-activity-widget.lua
index 769134c..019803e 100644
--- a/github-activity-widget/github-activity-widget.lua
+++ b/github-activity-widget/github-activity-widget.lua
@@ -139,13 +139,12 @@ local function worker(args)
 
     github_widget:set_icon(icon)
 
-
     local rows = {
         { widget = wibox.widget.textbox },
         layout = wibox.layout.fixed.vertical,
     }
 
-    local update_widget = function(widget, stdout, stderr, _, _)
+    local rebuild_widget = function(widget, stdout, stderr, _, _)
         if stderr ~= '' then
             show_warning(stderr)
             return
@@ -260,7 +259,7 @@ local function worker(args)
                             popup.visible = not popup.visible
                         else
                             spawn.easy_async(string.format(GET_EVENTS_CMD, CACHE_DIR, number_of_events), function (stdout, stderr)
-                                update_widget(github_widget, stdout, stderr)
+                                rebuild_widget(github_widget, stdout, stderr)
                                 popup:move_next_to(mouse.current_widget_geometry)
                             end)
                         end
@@ -268,6 +267,7 @@ local function worker(args)
             )
     )
 
+    -- Calls GitHub event API and stores response in "cache" file
     gears.timer {
         timeout   = 600,
         call_now  = true,
diff --git a/github-activity-widget/screenshot.png b/github-activity-widget/screenshot.png
new file mode 100644
index 0000000..175a755
Binary files /dev/null and b/github-activity-widget/screenshot.png differ