On 05/29/2010 04:58 PM, Heinrich Apfelmus wrote:
Eric Kow once remarked that the wikibook is a "do-ocracy" which means that by doing something, like writing a chapter or making a change, you automatically get the right to do it.
I think I will quote you both in my user page :)
By the way, a principle that has helped me in my writing is that I try to keep it really short, even minimize the number of words I use to make a point. Great for clarity and readability, though a bit dry at times. I always imagine that I'm writing for a reader whose attention is really low and lasts only one additional paragraph, which is probably indeed the case for any reader after a certain amount of time. :)
As you probably noticed already, I am slightly more inclined to flowery, colourful language. Thankfully as of late I have been able to keep myself under check and not get too prolix. In any case, the book would certainly profit from some extra conciseness - some existing passages grow really tiring just because the same idea is reiterated one time too many. ---- About the writing of "Truth Values" and the reworking of "Type Basics" (which I started yesterday) there are two main outstanding questions: 1. In "Truth Values" your outline included introducing True/False pattern matching when discussing the boolean operators. At first I thought it wasn't a good idea, as explained on the Talk page. But now, after having a closer look at "Type Basics" and the examples therein, I realize that not introducing an idiom this elementary idiom early on might be pedagogically problematic, as it may induce newbies to do very simple things in obtuse ways (like defining something like (||) with guards). In that case, a brief example - with (||), not, etc. could easily be added to the Boolean operations section, but I am not sure on what would be a clear, simple and not misleading way of introducing pattern matching at this point (discussing the general PM concept would likely not work, and saying "you can define functions with multiple definitions in terms of cases for (quasi-literal?) values of the arguments" could get too confusing (mainly the "quasi-literal" part - which really means literals and argument-less constructors, but obviously we can't go that far at this point of the book). 2. I am starting to believe that "Type Basics" should be divided in two. More specifically, the first part would retain the introduction, the experiments of :t, the presentation of Char and String and the section about functional types. The second part would have the final section about type signatures in code and the new section on number types. Finally, "Lists and Tuples" would be sandwiched between the two parts. Reasons for the splitting include: * The examples on the final section make use of tuples and string concatenation. While we could just reduce them to simple Int/Char/Bool functions, I fear that simplifying the examples too much would weaken their didactic value in illustrating to readers how signatures are important in practice. The move would also help to make the intentional forward references in that uppercase example less scary. * Both the existing demonstration of type inference (which involves the signature of (==) ) and the discussions of numerical types involve polymorphism. It would make sense to have them at the same place, as a "background topic" of a module. Moreover, placing the second part after "Lists and Tuples" would allow us to introduce polymorphic types and type variables with lists and tuples, which is probably more intuitive and easier for a newbie to grasp, and then expand a bit the concept with the other discussions. * Sheer length. "Type Basics" currently weighs at 27k, and with the addition of the whole numerical types discussion it could easily get to the 40k range - which would certainly be very bad for readability. Having the number types discussion on a less crowded module would also give us more space to present very useful and practical things, such as the different division operators or functions like fromInt. As usual, the only thing I can't find out is a good pair of names for the modules. In any case, since the division is slightly arbitrary perhaps we should simply stick to "Type Basics I" and "Type Basics II". Regards, Daniel Mlot