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