On 12/12/06, Claus Reinke
if you're using Haskell at all, you *are* the Haskell community.
[..lots of "I searched, I found, I tried, I got this error, I thought, I tried this workaround, I got to this point, now I'm stuck here..]
I just wanted to comment that I find this kind of "experience report" very helpful, especially if someone does not give up at the first hurdle, and goes through the trouble of writing up all the frustrating steps and thoughts rather than summarizing ("it didn't work"/"I got it to work after some fiddling") - thanks!
Thank you! That's exactly the sort of report I was trying to give,
although (from my point of view) it's pretty hard to report this sort
of thing without feeling like you're giving a complaining and
ungrateful impression. It's nice to have the reassurance that I got my
message across.
On 12/12/06, Bayley, Alistair
Yes, this is embarrasing. We have made a number of assumptions which Paul exposed:
It's hardly embarrassing - as Claus pointed out, the developers of any package are *always* too close to the problem to see this sort of issue.
- users should know to do darcs get, then runhaskell Setup.hs configure/build/install - users should know to look for Haddock docs - users should know how to look for and install dependent libraries (Cabal-1.1.6.1, in this case)
Yes, those are probably the key ones I tripped up on.
If you're an experienced Haskell programmer then these assumptions are valid, so yes, we do need to do more for the novice.
One thing that (from my POV as a Windows user) helped enormously in the Python community was adding the ability to distutils (their Cabal equivalent) to build Windows binary installers. With that, it became relatively easy for developers to package up binaries of their libraries, which made the Windows experience a simple "download and run" one. I've no idea if that is a practical or useful goal for Cabal, and I anticipate it being a long time before I'm at a level of understanding where I could help in implementing it, but it may be something to think about.
- sample code for "trivial queries" (aka, I know about databases, but I need to see the way this particular library handles things, so that I can figure out whether it is the right one for me) is not obvious to find
We have made a reasonable effort in Takusen to document the API extensively, and give example code. The problem seems to be that the documentation is too well hidden: http://darcs.haskell.org/takusen/doc/html/Database-Enumerator.html
Yes, I suspect that's the case.
The best thing I can think of now is to put a reference to this in the README file. Any other ideas? I wanted to keep the documentation in Haddock (so that it stays close to, and hopefully consistent with, the source) but maybe that's not the best idea for this kind of documentation, which is really a HOW-TO manual.
Something as simple as "here's how to issue a query and print the results" in the README would have been enough for me. When I get to that point, I'll write a few lines and let you see what you think.
If you have any further Takusen-specific questions, don't hesitate to contact me. Also, if you're having trouble installing or chasing down dependent libraries then I should be able to help.
Thanks for the offer. As others have pointed out, the level of help available from "the community" is excellent - it's just that needing to ask for help puts off those of us who work on a "let's just play with this Haskell stuff while my backup runs" basis :-) The backup has finished now, so I must run. Thanks again! Paul.