Documentation (was: ANN: text 0.5, a major revision of the Unicode text library)
For anyone writing introductions to generic programming, take this as a plea from Haskellers everywhere. If one of the RWH authors can't understand how to make use of these techniques, what hope do the rest of us have? John Lato P.S. Some might wryly note that I'm the maintainer of a package which is also known for incomprehensible documentation. To which I would reply that our effort is much newer, I consider it a problem, and it's being worked on, contrasted to the state of GP where similarly impenetrable documentation has been and continues to be the norm.
From: "Bryan O'Sullivan"
I think maybe someone else will have to take a crack at a Data instance for Text, because the documentation for Data.Data is not written in English. In its syntax and structure, it closely hews to what we think of as English, but it is the kind of documentation that can only be understood by someone who already knows what it is going to say.
This is an exemplar of my experience with the cottage industry of generic programming in Haskell: I'd really quite like to use the stuff, but for goodness's sake, o beloved researchers, please aim your expository papers at non-specialists once in a while. An endless chain of papers of the form "my technique, which you won't understand, is better than this other technique, which you haven't read about and won't anyway understand, in subtle ways that you won't understand" does not feel to me like progress.
Yours in some misery and frustration, Bryan.
On 11 Oct 2009, at 13:58, John Lato wrote:
For anyone writing introductions to generic programming, take this as a plea from Haskellers everywhere. If one of the RWH authors can't understand how to make use of these techniques, what hope do the rest of us have?
John Lato
P.S. Some might wryly note that I'm the maintainer of a package which is also known for incomprehensible documentation. To which I would reply that our effort is much newer, I consider it a problem, and it's being worked on, contrasted to the state of GP where similarly impenetrable documentation has been and continues to be the norm.
You could say that about most documentation (for Haskell and beyond). Apparently, programmers like programming better than documenting. The effect of this is that less people use their programming, making their efforts redundant. Silly really, considering programmers are (allegedly:) intelligent. Iain
On Sun, Oct 11, 2009 at 8:55 AM, Iain Barnett
On 11 Oct 2009, at 13:58, John Lato wrote:
For anyone writing introductions to generic programming, take this as a plea from Haskellers everywhere. If one of the RWH authors can't understand how to make use of these techniques, what hope do the rest of us have?
John Lato
P.S. Some might wryly note that I'm the maintainer of a package which is also known for incomprehensible documentation. To which I would reply that our effort is much newer, I consider it a problem, and it's being worked on, contrasted to the state of GP where similarly impenetrable documentation has been and continues to be the norm.
You could say that about most documentation (for Haskell and beyond). Apparently, programmers like programming better than documenting. The effect of this is that less people use their programming, making their efforts redundant.
Silly really, considering programmers are (allegedly:) intelligent.
Apparently, programmers like programming better than reading as well... in my experience.
Hi John, On Sun, Oct 11, 2009 at 14:58, John Lato wrote:
For anyone writing introductions to generic programming, take this as a plea from Haskellers everywhere. If one of the RWH authors can't understand how to make use of these techniques, what hope do the rest of us have?
I would like to help you with this problem, though with a different library. You can find EMGM [1] on Hackage. If you have a problem with the documentation there, please let me know. I would consider it a bug. To understand it, however, you should consider reading the tech report "Libraries for Generic Programming in Haskell" [2], an extended version of an article in a recently published collection of lecture notes from the 2008 Advanced Functional Programming Summer School [3]. [1] http://hackage.haskell.org/package/emgm [2] http://www.cs.uu.nl/research/techreps/UU-CS-2008-025.html [3] http://www.springerlink.com/content/978-3-642-04651-3 I agree that a lot more documentation could help, but I hope this helps. Regards, Sean
Hi, While I agree that the documentation of Data.Generics is not perfect, I do not think it is possible to have the haddock documentation be self-contained. For a thorough understanding of syb, a user has to read the two initial papers, which are linked from the haddock documentation. I also do not think it's reasonable to explain all the details beyond monads in the Control.Monad haddock, for instance. For the problem at hand (a Data instance for Text), I can only say that generic programming and abstract datatypes do not mix too well (although there is work on the area, see [1]). Generics work by exploiting the structure of types, and if that structure is explicitly kept hidden then (rather ad hoc) workarounds have to be used. See, for example, the Data instance for Array: -- The Data instance for Array preserves data abstraction at the cost of
-- inefficiency. We omit reflection services for the sake of data abstraction. instance (Typeable a, Data b, Ix a) => Data (Array a b) where gfoldl f z a = z (listArray (bounds a)) `f` (elems a) toConstr _ = error "toConstr" gunfold _ _ = error "gunfold" dataTypeOf _ = mkNorepType "Data.Array.Array"
Cheers,
Pedro
[1] http://www.comlab.ox.ac.uk/publications/publication1385-abstract.html
On Sun, Oct 11, 2009 at 14:58, John Lato
For anyone writing introductions to generic programming, take this as a plea from Haskellers everywhere. If one of the RWH authors can't understand how to make use of these techniques, what hope do the rest of us have?
John Lato
P.S. Some might wryly note that I'm the maintainer of a package which is also known for incomprehensible documentation. To which I would reply that our effort is much newer, I consider it a problem, and it's being worked on, contrasted to the state of GP where similarly impenetrable documentation has been and continues to be the norm.
From: "Bryan O'Sullivan"
I think maybe someone else will have to take a crack at a Data instance
for
Text, because the documentation for Data.Data is not written in English. In its syntax and structure, it closely hews to what we think of as English, but it is the kind of documentation that can only be understood by someone who already knows what it is going to say.
This is an exemplar of my experience with the cottage industry of generic programming in Haskell: I'd really quite like to use the stuff, but for goodness's sake, o beloved researchers, please aim your expository papers at non-specialists once in a while. An endless chain of papers of the form "my technique, which you won't understand, is better than this other technique, which you haven't read about and won't anyway understand, in subtle ways that you won't understand" does not feel to me like progress.
Yours in some misery and frustration, Bryan.
Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
participants (5)
-
Derek Elkins -
Iain Barnett -
John Lato -
José Pedro Magalhães -
Sean Leather