doc: Add a common problem section

docs/90-FAQ.md

@@ -8,6 +8,50 @@ The name *Awesome* comes from the English word *awesome* often used by the
 character [Barney Stinson](http://en.wikipedia.org/wiki/Barney_Stinson)
 from the TV series HIMYM.
 
+## Common issues
+
+### My screens are not configured correctly
+
+Awesome is a window manager, not a desktop environment. To configure your
+screens, the `xrandr` tool or various GUI applications exist. For more
+information, refer to the
+[Arch Linux wiki](https://wiki.archlinux.org/index.php/xrandr).
+
+### There is a noticeable delay with inputs
+
+There are two common causes for this:
+
+The first is a display driver issue where painting on the screen takes long
+time. All input events (keyboard and mouse) are processed in the main thread.
+The drawing is also locking the main thread to avoid artifacts and race
+ccontiditions. If there is a delay with the painting, it will delay the inputs.
+The solution to this problem is using a compositing manager such as 
+[compton](https://github.com/chjj/compton) or the older `xcompmgr`. This will
+move painting to another process and fully mitigate the issue.
+
+The second one is when using `io.popen` or other blocking functions in `rc.lua`
+and most commonly manifests itself as occasional freezes instead of a generic delay.
+Do **not** use such functions and prefer `awful.spawn.easy_async`,
+`awful.widget.watch` or the GIO async API. Even if you *think* a command is
+fast enough and won't impact the main event loop iteration time, you are wrong.
+*Every* calls to `io.open` are impacted by the system `iowait` queue and can
+spend hundreds of milliseconds blocked *before* being executed. Note that
+some common widget or probe libraries such as
+[Vicious](https://github.com/Mic92/vicious) do not follow this
+advice currently and are known to cause input lag on some systems (but not all).
+
+In both case, a warning like:
+
+    2018-01-23 09:58:48 W: awesome: a_glib_poll:432: Last main loop iteration took 14.416777 seconds! Increasing limit for this warning to that value
+
+will be printed to warn you about the issue.
+
+### The applications look ugly
+
+Awesome is a window manager, not a desktop environment. It does not
+provide a theme daemon. For more information about how to manage the
+look and feel of applications, refer to the
+[Arch Linux Wiki](https://wiki.archlinux.org/index.php/Category:Eye_candy).
 
 ## Configuration