Re: request for review: lbzip2
ERSEK Laszlo <lacos@caesar.elte.hu> writes:
> On Mon, 5 Oct 2009, Justin B Rye wrote:
> > There's nothing in either package description that would help me
> > decide which to install, except that pbzip2 gives me the hint that
> > there's no point having either on my old uniprocessor desktop.
>
> The long description of lbzip2 details the exact performance gap left
> by pbzip2 that lbzip2 covers.
The package description should not *detail* the differences; rather, it
should give enough information that the reader can make a decision about
whether to *investigate further*.
> Notice how your (perfectly valid) remark:
You seem to be trying to wag a finger at us for missing some kind of
debating point. We're not here to make robust rhetorical proofs of
anything; we're here to proof your use of language as a means of
communication.
> > There's nothing in either package description that would help me
> > decide which to install
>
> could be fixed by copying *more* technical information from the
> documentation into the long package description, while Ben advises
> exactly against that.
The description already lacks focus on what the reader needs to know.
Putting *more* technical information in, though, would be against the
goals already explicated: to help the reader make a decision.
> "It isn't restricted to regular files on input, nor output."
This might be better put in (brief, please!) terms of what its
capability is. Perhaps:
It can operate on streams (stdin and stdout) as well as files.
ERSEK Laszlo <lacos@caesar.elte.hu> writes:
> To tell the truth, I wanted to squeeze as much immediately usable
> technical information into the long description as possible.
This is a mistake. I am arguing (and I believe Justin agrees) that this
attempt to cram such detail into the package description is to the
detriment of its effectiveness as a communication of the information the
reader needs at that point.
> lbzip2 is meant for "power users", it's deliberately not a drop in
> replacement for bzip2. When I'm looking for a "power tool", I like to
> see as much specifics as possible in the output of 'apt-cache show'.
I think you lack the objectivity of someone who isn't specifically
versed in your particular package. As it stands, the level *and* volume
of detail in the package description need to be significantly reduced
before it will be useful for making a decision on whether to investigate
the package further.
> > These [reports on performance benchmark tests] seem quite redundant,
> > and very likely to be out of date whenever a new release is made.
> > Why are they in the description at all?
>
> This is the (truthful) marketing blurb to quickly lure users into
> trying out lbzip2. "Wow, so much speedup on an old machine!", they
> exlaim, furiosly typing "apt-get install". :)
>
> On a more serious note, this section doesn't need to be up-to-date at
> all. It should just give an example that lbzip2 is for real (and was
> for real, "ages ago"), but be correct at the same time.
That doesn't wash. If you want to say it's fast, and you know you can
justify the claim, then claim it in the description, and move on. It is
unnecessary to attempt to jam all the specific data behind these claims
into the package description, and positively harmful to the field's
purpose.
Certainly, if you *have* supporting data and are willing to keep it
current, justify the claim in the documentation with as much detail as
you like. But the package meta-data is not the place for it.
--
\ “A free society is one where it is safe to be unpopular.” |
`\ —Adlai Ewing Stevenson |
_o__) |
Ben Finney
Reply to: