Manlio Perillo wrote:
I'm fine with current names.
However I would like to see better documentation, and examples.
You can't just have in the documentation: this is xxx from yyy branch of mathematics, see this paper.
You should explain how (and why) to use xxx.
Absolutely this! I would rather have to look up Monoid than see Appendable used for operations that don't fit my notion of appending. I don't care much what things are called as long as it's accurate. Even so, I typically find Haskell's documentation to be not very helpful, because it's aimed towards category theorists. That is, Haskell documentation often seems to take the approach "The reader is familiar with [branch of abstract mathematics], so knows all these concepts. The job of the documentation is to show how standard terminology from [branch of abstract math] is written in Haskell". The problem with this is that most people aren't familiar with general abstract nonsense, and this documentation is useless for those, i.e. most, people. In fact, most people don't care about how abstract nonsense is written in Haskell. They care about solving their particular problems, and are only interested in abstract nonsense to the sense that it can be useful in solving those problems. Overwhelmingly the documentation does not show how particular concepts apply to actual programming problems, or any concrete problems at all. Here is the current complete documentation for Data.Monoid 'mappend', which happens to be a good example of which I speak: An associative operation That could mean anything. There are lots of associative operations. Should I believe the name that somehow this operation is append-like? If so, and I'm using a list instance, where are items appended to? Is it an append onto the tail of the list, or is it really a cons? I would expect the documentation to cover this, but it doesn't. Far too often the documentation fails to provide this sort of useful, practical information. This is the problem faced by an abstract-nonsense unaware user: I want to accomplish [some task]. Some blogger wrote that [monoids, functors, arrows, etc.] provide a good solution. But when I look up [monoids, functors, etc.] in [some academic paper], it doesn't show how these concepts apply to the problem at hand, or indeed any programming problem at all. In fact, I can't even understand what the doc says without first learning about [even more abstract stuff]. So now the user needs to develop a strong background in [some abstract topic] he/she doesn't care about just to figure out *if* that abstract topic could possibly be useful. At this point most users will give up. If instead they had access to documentation that says "[Monoids] are useful programming abstractions because they can solve problems A, B, and C in these manners, and incidentally they can do all this other stuff too", the same users would not only stick with Haskell longer, they would increase their theoretical awareness at the same time. I think even the most elitist Haskell users would think this is a good outcome. Of course this better documentation would need to be written. Somebody upthread (Duncan?) suggested that suitable individuals may not exist, and I agree with that. Of people who understand the material well enough to document it, many are busy doing other work, and many have no interest or are ideologically opposed to writing documentation of this type. This situation reminds me very much of a particularly well-known article by Milton Babbitt, "Who Cares If You Listen." I expect that many Haskellers would find it interesting at the least. John Lato