[Haskell-cafe] Re: a cabal/database lib experience
claus.reinke at talk21.com
Tue Dec 12 09:40:44 EST 2006
>> absolutely, this has occurred to me too. There should be a stanard Cabal
>> README file, and Don's mkcabal tool could drop it in the tree.
> This occurred to me too. My current plan for mkcabal is that it creates:
> based on a series of interactive questions, or command line args.
is mkcabal going to be a standard part of cabal installations?
btw, here is some suggested text for the useful "how to write.." page you
started (I know it is a wiki, but I don't want to mess up the page at this point;-).
-------------------------------------------- 0. The intended user experience
When Haskell programmers go out in search of existing functionality, be it a
library, a tool, or an application, the intended approach is roughly this:
1 visit haskell.org,
2 find the library/program they are looking for
(if not found, try mailing list; if it is hidden, try improving haskell.org;
if it does not exist, try contributing code/documentation/requirements/..)
but each of these steps is endangered by several potential road blocks, and
code authors can do a lot to help code users avoid such blocks. Even if steps
1/2 are successful, and ensuring step 5 is the main concern of code authors
and users, it is often steps 3/4 that get in the way:
- which is the latest version? what state is it in? is it still maintained/in use?
- what are its aims? where is the documentation?
- which is the right version for given OS and Haskell implementation?
- how is it packaged, and what tools are needed to get and unpack it?
- how is it installed, and what tools are needed to install it?
- how do we avoid IDR (infinite dependency recursion)?
- how do we provide/acquire the knowledge and tool-chains needed?
There is a well-established tradition for communicating the answers to
these questions: the README text file, placed in a prominent position
at the code's location (these days often accompanied, but not replaced,
by a more extensive web page). But as other communities, the Haskell
community has Haskell-specific answers to many of these questions,
independent of the particular Haskell code to publish.
This document is all about how to publish your Haskell code in such a
way as to make the Haskell code users' experience as smooth as possible.
Until there is a version of this text targetted more specifically at code users,
they might find it helpful to browse this page for insights into the Haskell
code authors' mind- and tool-set.
More information about the Haskell-Cafe