diff --git a/Makefile b/Makefile
index 0e14092..76f8b4b 100644
--- a/Makefile
+++ b/Makefile
@@ -41,7 +41,7 @@ CONFS := doc/pusb.conf-dist
CONFS_DEST := $(DESTDIR)/etc/pusb
# Doc
-DOCS := doc/installation doc/configuration doc/upgrading
+DOCS := doc/INSTALLATION doc/CONFIGURATION doc/UPGRADING doc/FAQ
DOCS_DEST := $(DESTDIR)/usr/share/doc/pamusb
# Man
diff --git a/doc/configuration b/doc/CONFIGURATION
similarity index 100%
rename from doc/configuration
rename to doc/CONFIGURATION
diff --git a/doc/FAQ b/doc/FAQ
new file mode 100644
index 0000000..37c76f3
--- /dev/null
+++ b/doc/FAQ
@@ -0,0 +1,21 @@
+====== Frequently Asked Questions ======
+
+> Q: Can I use my USB drive as usual ?
+>> A: Yes. pam_usb only occupies a few kilobytes of the device's space.
+
+> Q: What if I lose or break my USB key ? Will I be able to log back in ?
+>> A: Sure. Your usual password will be asked.
+
+> Q: How is the USB key identified ?
+>> A: The USB device is both identified by its manufacturer attributes (vendor,
+product, serial number) and by a few random bytes called one time pads that
+pam_usb writes and updates on the USB device upon authentication.
+
+> Q: What if someone copies the content of my flash drive ? Will she/he be able
+to log into my account ?
+>> A: Even if that person manages to fake your device's attributes (vendor,
+product, serial number, UUID), the one time pad they copied will be outdated as
+soon as you authenticate.
+
+> Q: Is my USB drive compatible with pam_usb ?
+>> A: About every USB flash drive will work with pam_usb.
diff --git a/doc/installation b/doc/INSTALLATION
similarity index 78%
rename from doc/installation
rename to doc/INSTALLATION
index 4990768..85d2307 100644
--- a/doc/installation
+++ b/doc/INSTALLATION
@@ -5,6 +5,7 @@ an older version of pamusb.
===== Requirements =====
* Requirements for pam_usb and pusb_check:
+ * libpam
* libhal-storage
* libxml2
@@ -154,6 +155,49 @@ For instance, with GNOME:
- Enter pusb_hotplug and press OK
- Press Close
+====== Troubleshooting ======
+
+===== Log Analysis =====
+
+Both pam_usb.so and pusb_hotplug use the syslog facility to log authentication
+attempts.
+This can be useful for GUI-driven applications (for instance GDM) where you
+don't get to see console output.
+Messages are logged with the AUTH facility, they are usually written to
+/var/log/auth.log but may vary
+depending on the operating system you're using.
+
+# tail -f /var/log/auth.log
+pusb_hotplug[25429]: Device "sandisk" has been inserted. Performing
+verification...
+pusb_hotplug[25429]: Executing "/usr/bin/pusb_check -q -c /etc/pusb/pusb.conf -u
+scox -s pusb_hotplug -a"
+pam_usb[25485]: Authentication request for user "scox" (pusb_hotplug)
+pam_usb[25485]: Device "sandisk" is connected (good).
+pam_usb[25485]: Access granted.
+pusb_hotplug[25429]: Authentication succeeded. Unlocking user "scox"...
+pusb_hotplug[25429]: Unlocked.
+
+===== Enabling debug =====
+
+Enabling debug messages may help you find out what's wrong.
+
+To enable them, edit /etc/pusb/pusb.conf and set the following option:
+
+
+
+
+If you wish, you could enable debug messages only for a specific user, device or
+service.
+For instance, if you want to enable debug messages only for the sudo service,
+you could do the following:
+
+
+
+
+
+
+
====== It works - What next ? ======
* Have a look at the configuration documentation
diff --git a/doc/upgrading b/doc/UPGRADING
similarity index 100%
rename from doc/upgrading
rename to doc/UPGRADING
diff --git a/doc/pusb_adm.1.gz b/doc/pusb_adm.1.gz
index c2bb910..2d26449 100644
Binary files a/doc/pusb_adm.1.gz and b/doc/pusb_adm.1.gz differ
diff --git a/doc/pusb_check.1.gz b/doc/pusb_check.1.gz
index 3bfc378..7df7177 100644
Binary files a/doc/pusb_check.1.gz and b/doc/pusb_check.1.gz differ
diff --git a/doc/pusb_hotplug.1.gz b/doc/pusb_hotplug.1.gz
index 1bd9fe1..c1e7923 100644
Binary files a/doc/pusb_hotplug.1.gz and b/doc/pusb_hotplug.1.gz differ