[xmonad] xmonad as an outsider

[Weeble]

I have been reading the xmonad development thread, and it got me to
thinking about my experiences with xmonad. I definitely think things
could be improved, but I'm not sure how would be best. Maybe it's all
a documentation thing, or maybe some of it could be new or changed
APIs. I'll just try to explain how I have experienced xmonad, and what
gave me problems.

First of all, as background, I am a programmer. I did a little Haskell
at university, but not much and I use it so rarely that I can never
remember the syntax. Mostly I program in C#, C++, Python and a little
bit of Coffeescript. I run Ubuntu on a laptop and mostly only install
stuff via apt-get. I like the command-line and vim, but I'm no
anti-mouse purist and spend a lot of time using only the mouse or the
touchpad while browsing the web.

I think I first installed xmonad via apt-get, and at some point had
some problem that meant moving to cabal or darcs. That was a bit of a
pain, especially trying to understand where each of these things had
put files and knowing whether I'd successfully uninstalled them later.
What is much more of a pain is months later when I try to change
something and realise I need to upgrade and then I'm not even sure how
I installed xmonad in the first place, so I'm not sure what I need to
do to update it. After an upgrade to a new version of Ubuntu there's
generally a period of a few weeks before I find the time to figure out
how to get xmonad up and running again.

Configuring xmonad is generally pretty mystifying. Even though I have
a basic knowledge of Haskell, it's often very hard to untangle things
in the config file or in examples. Problems I've had:

* Strange symbols, like ".|.", "|||", "-->", "=?", "<&&>". These can't
be Googled for, so it's hard to find out what they do or where they're
defined. Haskell already has lots of operators that aren't
particularly familiar to programmers coming from other languages, so
this just seems to add to the confusion.

* Hard to find out where functions are defined. Example configuration
files generally import all modules into the one big namespace. In
Python, the equivalent construct, "from foo import *" is generally
discouraged for this reason, but I don't know what's conventional in
Haskell. It seems the forms "import Module (x,y,z)" or "import
qualified Module" would be better for example configuration files, as
they aid discoverability: then when I see a name used in a
configuration file I can easily see which module it came from without
having to grep through source files.

* Poor layout documentation. One of the things I was most interested
when I was a new user was in finding out what layouts were available
and how to compose them. I found the layout documentation to be very
limited. There's no overview and there are no diagrams, just a great
big list of layout names, so to find anything you pretty much have to
try them all one by one. Even worse, some of them require arguments
that they do not document. E.g.
http://xmonad.org/xmonad-docs/xmonad-contrib/XMonad-Layout-Dishes.html
If there is somewhere that shows example screenshots of all these
layouts, it would be good if it was more prominently linked from the
docs.

* Baffling failure messages. If you make a mistake in your xmonad
configuration, or if you upgrade and the API for something has
changed, the error messages are generally very hard to understand, and
it can take quite a deep understanding of Haskell to realise that you
just missed out an argument or used the wrong operator.

I think most of these things can be improved, though maybe not the
error messages. I really love *using* xmonad, and I've not found
another window manager that I'm nearly as happy with, but the horror
of *configuring* xmonad wastes a lot of my time and makes me
disinclined to recommend it to others.

Weeble.