Hi Andrea, I have been missing a lot of the activity on xmonad in the last two weeks and thus I was somewhat puzzled by the main inversion leaving the darcs version not compiling on my machine. Meanwhile I upgraded to GHC 6.8 and read your documentation and now I got a good idea of the new xmonad philosophy. I still need to find some time to actually convert my config, but the documentation helped a lot to understand how to do it (well, at least to make me think that I understand how to do that ;-) ). Regarding the issue about non-haskellers having to handle things like Data.Map for modifying keys, I think you made a good move to mention the EZConfig and CustomKeys modules in the documentation. Especially the EZConfig thing looks quite intuitive and easy (though I can't judge if there are conceptual drawbacks with respect to CustomKeys). So, the Documentation module is indeed great work. I also like Don's idea of making it a wiki article which would probably make it easier for non-coders to add documentation (because they don't need to get into recording and sending darcs patches), but on the other hand your integrated-with-the-source approach is very stylish and I don't know how many "normal" (i.e. not code-contributing) users would be able to document how to use features that others write but do not document ;-) Cheers, Christian Andrea Rossato wrote:
Hi.
Sorry if I keep bothering with that. I don't know why, but documentation is something I care quite a lot about, and I don't know if what I'm doing, which is also quire time consuming, is worthy.
I'm writing the new Documentation module[1] as if it were a tutorial for haskell beginners or intermediate users who want to start playing with configuring xmonad. The idea, in part supported by David if I did correctly understand him, was to have an introduction to xmonad internals...
...which brings me to two question:
1. who should be the audience of a documentation like that, which remains a Haddock library documentation?
2. what is a user required to know in order to being actually able to configure xmonad?
I mean, if I get it right, customizing the key bindings means dealing with a Data.Map.Map, with insertions, unions, and so forth. To be done explicitly in Haskell. Which makes configuration so powerful and everything so exciting. This is why we like XMonad, after all. This is why we did not write a window manager, but a library to let every user write a window manager in 3 lines of haskell! But if you don't know Haskell at all and don't care anything about it?
I think I need some help documenting that: should I stick with my initial proposal or should we find a better way to write something targeted at a broader audience? i think that, in this second case, things get more complicated. And is it the right place for something intended for the general user?
Any suggestion is welcome.
Andrea
[1] http://gorgias.mine.nu/xmonad/xmonad-contrib/Documentation.html
_______________________________________________ xmonad mailing list xmonad@haskell.org http://www.haskell.org/mailman/listinfo/xmonad
-- Christian Thiemann mail@christian-thiemann.de