Re: Rewriting a famous library and using the same name: pros and consf
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!
An advantage of separate names (both for the package name and module name-space) is that its easier to have both packages installed at the same time - the old one to work with while learning the package, the new one if other installed packages depend on it. This can still be done with package-hiding but its less straight-forward.
With proper .cabal files and dependency bounds this isn't an issue. If you're working in ghci I think it's the same amount of work either way, at least with my workflow.
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
On 9 June 2010 12:11, Jason Dagit
Or write translator tools for upgrading to the new API :) Pipe dream? Maybe.
Too an extent, yes: the types are more generalised so it's going to be difficult to do automatic translations. However, Thomas has demonstrated that you can write any instance of the new class as an instance of the old classes and vice versa just using class methods... -- Ivan Lazar Miljenovic Ivan.Miljenovic@gmail.com IvanMiljenovic.wordpress.com
Hi John My feeling is that a beginner would be transferring almost all of the the knowledge they gained from Parsec 2.1 if they moved to Parsec 3.0. We're talking about "famous" libraries, so the library was previously valuable and useful before the "discontinuous" version change. In Parsec 3.0's case the discontinuous change revised the parser type (Parser -> ParserT), the hierarchy for importing modules and where you find the run functions. These are almost insignificant when an experienced user wants to move their code from 2.1 to 3.0, but they may well be significant hurdles for a Haskell beginner working from examples written with 2.1 (there are no examples in the Parsec 3.0 distribution) or working through the manual. Daan Leijen's Parsec manual, the QuickCheck paper, Paul Hudak's Haskore tutorial were all "authored" - it would seem inappropriate to update them. Of course, a revised project could supply a commentary on the original documentation - "Parsec - Cliff's notes", detailing where the differences are, but in practice they don't vis my point that libraries advance ahead of their documentation. Best wishes Stephen
participants (4)
-
Ivan Miljenovic -
Jason Dagit -
John Lato -
Stephen Tetley