[Haskell-cafe] Package documentation complaints -- and a suggestion

[wren ng thornton]

On 10/25/11 3:54 AM, Gregory Collins wrote:
> On Tue, Oct 25, 2011 at 4:34 AM, wren ng thornton<wren at freegeek.org>  wrote:
>> I'm not so sure about that exemption. The "experimental" stability level
>> seems to be the norm on Hackage and often means "I use this for real
>> projects, but because I use it for real projects I'm not quite willing to
>> hammer the API in stone just yet".
>>
>> ...
>>
>> Before dealing with automatic documentation requirements, perhaps it'd be
>> better to develop a standard consensus on the terms used in the stability
>> field and actively advocating for people to adopt it, as was done with the
>> PVP.
>
> I think there's no need to cajole people into it -- if Hackage 2 puts
> "stable" packages on a different / better list, there's your social
> pressure. Right now the stability flag in the .cabal file, as you
> pointed out, is almost completely content-free.

The problem isn't social pressure to be stable, it's the ambiguity of 
what "stable" means. If Hackage 2 institutes a policy whereby things 
claiming to be stable are treated better, then "stable" is likely to 
become the new "experimental". Just because I call something stable 
doesn't mean that it is. Just because I give something enough 
documentation so appease the bots so that I'm allowed to call it stable 
doesn't mean that it is. Frankly, giving a one-line synopsis of what a 
function does isn't a high enough barrier to entry to keep someone from 
abusing the system in order to self-select which index page they get put on.

The only way to get a consensus about what "stable", "experimental", etc 
mean is ...to get a consensus about what they mean. It's exactly the 
same thing as the PVP: in order to get people to agree about what 
version increments mean, we need to get them to agree to mean whatever 
it is everybody else thinks they mean. Automating the verification of 
that agreement is a nice tool to have to hand, but it's meaningless 
without the agreement about what we're all engaged in.

-- 
Live well,
~wren