On Tue, Jun 8, 2010 at 6:28 PM, John Lato jwl...@gmail.com wrote:
From: Stephen Tetley stephen.tet...@gmail.com
Hello all
While new libraries develop at pace, their documentation rarely does;
so I'd have to disagree with John's claim that re-naming libraries
makes development by new users harder. I'd argue that having tutorials
not work for later revisions is more confusing than having various
packages doing the same thing. I'd also contend that beginners are
better off lagging behind the cutting edge and using Parsec 2,
QuickCheck 1, Haskore-vintage, as the earlier version all have
comprehensive documentation - Parsec 2 and Haskore have extensive
manual/tutorials, QuickCheck 1 was small enough that the original
QuickCheck paper covered its use.
Lagging behind the cutting edge is one thing, but learning
possibly-deprecated or soon-to-be-obsolete interfaces is another. I
would contend that in each case the intention is for the earlier
version to be superseded because of significant (hopefully
user-driven) benefits provided by the new design. Now beginners are
in the very frustrating situation of having invested time with a
codebase that they learn is obsolete. Depending on the significance
of the changes, some amount of that knowledge can be carried forward,
but it's a disheartening position to be in and I would expect a few
could give up entirely at that point. I think that's worse than
floundering around with no documentation at all.
Of course a better solution is for maintainers to update their manuals!
Or write translator tools for upgrading to the new API :) Pipe dream?
Maybe.
Jason
___
Haskell-Cafe mailing list
Haskell-Cafe@haskell.org
http://www.haskell.org/mailman/listinfo/haskell-cafe
