Re: zomg: discussion of package description
Martin Eberhard Schauer <Martin.E.Schauer@gmx.de> writes:
> Hi,
>
> today I found a package description which I consider improvable. I would
> like to suggest the maintainer a rewritten and hopefully improved version.
> But I am not experienced in writing english texts.
>
> Original:
>
> console-based libre.fm submission and radio client
>
> ZOMG is a console-based libre.fm client written in Z-Shell.
> It can submit the music tracks you play to libre.fm via the
> Audioscrobbler protocol, and it can play libre.fm radio stations.
> .
> It can also submit tracks to last.fm or any compatible GNU FM site.
>
> First attempt:
>
> text-mode libre.fm client with submission capability to internet radios
>
> ZOMG can play libre.fm radio stations and submit the music tracks
> you play to libre.fm, last.fm or any compatible GNU FM site.
Your version is an improvement in some respects. Congratulations!
Some further improvements I suggest:
* “with submission capability” is rather long-winded. A form of the verb
“can submit” would be simpler here.
* “internet radios” isn't clear. “internet radio stations” is better.
* The extended description should not assume that the reader knows
what's in the synopsis. Your extended description needs to include the
information about “text-mode”.
* With more information, the extended description will be clearer as
several shorter sentences.
* [Nitpick] I strongly prefer the “serial comma” as reducing ambiguity
in lists.
My suggestion for the description:
text-mode libre.fm client which can submit usage data to stations
ZOMG is a text-mode client for libre.fm internet radio stations. It
can submit the music tracks you play to libre.fm, last.fm, or any
compatible GNU FM site.
> LD: The original's first sentence partly repeats the headline.
> Therefore this part is redundant.
The extended description should be redundant with the synopsis. My
interpretation of Policy §3.4.1 and §3.4.2 is that there should be no
information in the synopsis that isn't also in the extended description,
since there's no guarantee the two fields will appear together.
> The average, prospective user wants to know what the program can do
> for him and not how it is implemented.
Agreed, there's no need for the description to talk about the
implementation language. You mightlike to add debtags with that
information <URL:http://debtags.alioth.debian.org/>, so that it will be
available in a structured machine-parseable form.
> Seperate paragraphs for sentences with related information (submission
> to different internet radios) don't make sense.
They often make a passage of text clearer, and easier to translate.
Those are quite valuable in the package description.
> Not adressed yet:
> Another translator wondered how to translate track. For me it is
> plausible, that track is short for the sound file plus metadata.
Hmm. The origin of the term is a groove on a wax cylinder or vinyl
album; the path (“track”) along which the playback needle is to travel,
carrying all the sound information. So it's quite clear to a NSoE (even
if they don't know the specific origin).
I have experienced difficulty translating that term, so I can
sympathise. Many non-English languages seem to take “track” as an opaque
technical term and not bother translating it.
--
\ “Oh, I love your magazine. My favorite section is ‘How To |
`\ Increase Your Word Power’. That thing is really, really, |
_o__) really... good.” —Homer, _The Simpsons_ |
Ben Finney
Reply to: