On Tue, Jun 8, 2010 at 6:28 PM, John Lato
From: Stephen Tetley
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