[xmonad] does it make any sense?

[Brent Yorgey]

On Nov 16, 2007 5:31 PM, Andrea Rossato <mailing_list at istitutocolli.org>
wrote:

> On Fri, Nov 16, 2007 at 01:46:46PM -0800, Don Stewart wrote:
> > One issue: why not develop this on the wiki, rather than in a src file?
> > I didn't understand the motivation there.
>
> The idea is to use haddock for editing purposes. That module should be
> a high level access to each module documentation. This was the idea.
> Not a tutorial or a wiki page.
>
> But, as I said, this is just a proposal. If you believe a wiki page
> would better fit our purposes we can get rid of this module and
> transfer that content to a wiki page.
>
> Andrea
>

Here are my thoughts.  I think there are really two distinct audiences here,
and there should be two distinct documents:

1. People who are just trying to configure xmonad.

I think Documentation.hs is a great document for these people.  It should be
straightforward, with detailed descriptions of simple things, and a
high-level overview of what extension modules are available. A lot of this
is already in Documentation.hs, and it's great. The pro of having this as
Haddock-generated documentation (as opposed to on the wiki) is that it can
automatically and easily link to the  Haddock documentation for other
contrib modules, which will automatically be up-to-date; there are no
problems with making sure a wiki document stays current and so on.  I think
it will also encourage developers of new modules to add links to their
documentation, since it is all right there in the source (rather than having
to remember to edit the wiki separately).  And of course we can have a link
to it on the wiki.

2. People who know a bit of Haskell and want to get a bit fancier with their
configuration, or write some new extensions.

Andrea, it seems that this is the kind of thing you have started putting in
Documentation.hs (starting with the section "Writing new extensions"), but I
think this should probably go on the wiki instead.  The problem is that I
think this document, written properly, will be VERY long!

I actually care very much about such a document and have a great vision of
what it could be, since I essentially started writing such a document a
couple months ago!  I started going through the xmonad source in order to
understand it, and, encouraged by Don, began writing an 'xmonad
commentary'.  I already have a bunch of commentary on StackSet, but have put
it on hold due to grad school apps, the big changes with 0.5, and so on.
Hopefully sometime soon I will have a chance to upload what I have to the
wiki so that others can work on it too.  My vision for this commentary is
that someone who knows some basic Haskell could read it and come away with
(a) a much deeper understanding of Haskell and the sorts of techniques that
are used; (b) an excitement for Haskell and what it makes possible, with
xmonad as a case study; and (c) (last but not least) the ability to
contribute new extension modules and so on.

-Brent
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://www.haskell.org/pipermail/xmonad/attachments/20071117/16376c46/attachment-0001.htm