does it make any sense?
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
mailing_list:
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?
One issue: why not develop this on the wiki, rather than in a src file? I didn't understand the motivation there. -- Don
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
On Nov 16, 2007 5:31 PM, Andrea Rossato
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
On Sat, Nov 17, 2007 at 12:17:27PM -0500, Brent Yorgey wrote:
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!
Well, what I have in mind is a brief (really) overview of the xmonad's internal working with reference (links) to the (quite good, I would say) haddock documentation of the code: main (now xmonad), the event handler, the X monad, and the layout type stuff. About the last one, I don't know, maybe I'm just plainly wrong, but after the LayoutClass change, with the 0.4 release, I had the feeling that new modules contributions have decreased - we would need one of those Don's graphs to verify this... I repeat, I may be wrong, but I think that all the type class stuff could be difficult to grasp to the coders who could be contributing code for xmonad. I think that a brief introduction for them could be helpful too. What do you think? Am I wrong with that?
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.
That would be really great I think, and if I had the time I would have started something like this. Please consider the possibility of starting it on the wiki, I could be helping somehow. Cheers, Andrea
mailing_list:
On Sat, Nov 17, 2007 at 12:17:27PM -0500, Brent Yorgey wrote:
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!
Well, what I have in mind is a brief (really) overview of the xmonad's internal working with reference (links) to the (quite good, I would say) haddock documentation of the code: main (now xmonad), the event handler, the X monad, and the layout type stuff.
About the last one, I don't know, maybe I'm just plainly wrong, but after the LayoutClass change, with the 0.4 release, I had the feeling that new modules contributions have decreased - we would need one of those Don's graphs to verify this... I repeat, I may be wrong, but I think that all the type class stuff could be difficult to grasp to the coders who could be contributing code for xmonad.
I think that a brief introduction for them could be helpful too. What do you think? Am I wrong with that?
I think you are write, Andrea. new extensions have dropped off, and some contributors have complained about problems munging types on the irc channel. There have been previous lulls in activity though, so its hard to assign it to the type changes to layouts, without further data. -- Don
On Nov 17, 2007 2:42 PM, Andrea Rossato
2. People who know a bit of Haskell and want to get a bit fancier with
On Sat, Nov 17, 2007 at 12:17:27PM -0500, Brent Yorgey wrote: 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!
Well, what I have in mind is a brief (really) overview of the xmonad's internal working with reference (links) to the (quite good, I would say) haddock documentation of the code: main (now xmonad), the event handler, the X monad, and the layout type stuff.
About the last one, I don't know, maybe I'm just plainly wrong, but after the LayoutClass change, with the 0.4 release, I had the feeling that new modules contributions have decreased - we would need one of those Don's graphs to verify this... I repeat, I may be wrong, but I think that all the type class stuff could be difficult to grasp to the coders who could be contributing code for xmonad.
I think that a brief introduction for them could be helpful too. What do you think? Am I wrong with that?
OK, yes, I agree, there is definitely space for a third audience: those who want a little guidance on how to jump into making their own extensions, but don't want to read an entire novel. =) I'm still not sure where such a thing should go -- whether it should go in Documentation.hs or on the wiki. That would be really great I think, and if I had the time I would have
started something like this. Please consider the possibility of starting it on the wiki, I could be helping somehow.
I'll see about putting what I have on the wiki soon. -Brent
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.
Another thing I forgot to mention is the need to have some common documentation about the performing of some configuration steps each module may be referring to. For instance, many modules need to give instructions on how to add a key binding to call a function they export. This way they can directly link the appropriate section of Documentation.hs. If the way of adding key bindings will be changed then we will have just one place to update, whereas lately we have been updating more documentation than loc...;) Andrea
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
On Fri, Nov 16, 2007 at 11:31:10PM +0100, Christian Thiemann wrote:
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
Thanks Christian for your kind words. I'm just having a look at the darcs repository of haddock (I didn't read the code, but I noticed the new directory structure and I've just compiled it): the documentation I'm writing as source code should be exportable to a wiki format (or other stuff) with a very little effort. If I understand correctly now haddock is a library and writing a backend for a wiki text export should be easy. But I could be totally wrong on that... ;) BTW, I'll keep on updating that file for now. We can later decide how to deal with this issue. Cheers, Andrea
participants (4)
-
Andrea Rossato -
Brent Yorgey -
Christian Thiemann -
Don Stewart