diff --git a/doc/assistant.mdwn b/doc/assistant.mdwn
index 6d9bab2912..05f987a9c9 100644
--- a/doc/assistant.mdwn
+++ b/doc/assistant.mdwn
@@ -1,6 +1,38 @@
-The git-annex assistant makes git-annex easy to use by providing a
-automatic management and syncing of your files, and a friendly web frontend
-for configuration.
+The git-annex assistant creates a folder on each of your computers, which
+it keeps synchronised, so its contents are the same whichever computer it's
+used on. It's very easy to use, and has all the power of git and git-annex
+underneath.
+
+## quick start
+
+To get started with the git-annex assistant, just run it from the menu:
+
+[[!img assistant/menu.png]]
+
+It'll prompt you to set up the folder:
+
+[[!img assistant/makerepo.png]]
+
+Then any changes you make to its folder will automatically be committed to
+git, and synced to repositories on other computers. You can use the
+interface to add repositories and control the git-annex assistant.
+
+[[!img assistant/running.png]]
+
+## command line start
+
+The git-annex assistant will automatically be started when you log in to
+desktop environments like Gnome, XFCE, and KDE, and the menu item
+shown above can be used to open the webapp. On other systems, you may need
+to start it by hand.
+
+To start the webapp, run `git annex webapp` at the command line.
+
+To start the assistant without opening the webapp, 
+you can run the command "git annex assistant --autostart". This is a
+good thing to configure your system to run automatically when you log in.
+
+## colophon
 
 The git-annex assistant is being
 [crowd funded on
diff --git a/doc/assistant/makerepo.png b/doc/assistant/makerepo.png
new file mode 100644
index 0000000000..e8f1b26216
Binary files /dev/null and b/doc/assistant/makerepo.png differ
diff --git a/doc/assistant/menu.png b/doc/assistant/menu.png
new file mode 100644
index 0000000000..aac88e9323
Binary files /dev/null and b/doc/assistant/menu.png differ
diff --git a/doc/assistant/running.png b/doc/assistant/running.png
new file mode 100644
index 0000000000..8c3b0eaf24
Binary files /dev/null and b/doc/assistant/running.png differ