Hi
On Thursday 21 February 2008 19:07, Noah Slater wrote:
> On Thu, Feb 21, 2008 at 08:44:00AM +0100, Christian Perrier wrote:
> > Sorry, this is precisely rationale I fight against. Just saying "if you
> > don't know what this is, you don't need this" defeats the purpose of
> > packages descriptions.
Fully agree.
>
> In the general case maybe but for this I disagree. For highly specialised
> development tools such as RDF there is really no need to be verbose about
> what the name actually means because those who would be interested
> already know.
>
<sarcasm mode on>
I know what RDF means. RDF is an abbreviation for radio direction finder. I
guess there are digital RDFs now, and you're packaged python utils for
dealing with then.
Or maybe it's python utils for manipulating a Reuters Data Feed.
Or for a Radial distribution function.
Or one of half a dozen other possible meanings for RDF. [0]
</sarcasm mode off>
Even though a package is highly specialised, you should make a package
description as understandable as possible by everyday users.
Consider the following (made up) example.
feamodel-utils - utils for manipulating FEA models
Utilities for manipulating FEA models. It supports ABACA, FEDME and FrEA
format models.
feamodel-utils - utils for manipulating Finite Element Analysis (FEA) models
Utilities for manipulating Finite Element Analysis (FEA) models. It
supports ABACA, FEDME and FrEA format models.
The first is pure gobbledygook to anyone who does not recognise the key
acronym. Because they can't understand what you're talking about, you run
the risk of alienating them.
By expanding the key acronym, the second is much more understandable. As
such it's much less alienating. By limiting the key sentence is to words
everybody can understand, it provides all users with sufficient information
to decide whether the package is interesting to them/someone they know.
> I took a look at the current state of affairs w/r to RDF:
>
> [EMAIL PROTECTED]: ~ $ apt-cache search rdf | grep rdf
> liblrdf0 - a library to manipulate RDF files describing LADSPA plugins
Short and long descriptions use RDF in context.
> liblrdf0-dev - liblrdf0 development files
Short description refers to liblrdf0, long description provides context.
> librdf-perl - Perl language bindings for the Redland RDF library
Qualifies RDF in short description, expands RDF in long description.
> librdf-ruby - Ruby 1.8 language bindings for the Redland RDF library
Qualifies RDF in short description, expands RDF in long description.
> librdf0 - Redland Resource Description Framework (RDF) library
RDF expanded and qualified in short description.
> librdf0-dev - Redland RDF library development libraries and headers
Qualifies RDF in short and long descriptions.
> php5-librdf - PHP5 language bindings for the Redland RDF library
Qualifies RDF in short description, expands RDF in long description.
> python-librdf - Python language bindings for the Redland RDF library
Qualifies RDF in short description, expands RDF in long description.
> python-rdflib - RDF library containing an RDF triple store and RDF/XML
Short and long descriptions provide context.
>
> Only one of these packages is expanding the acronym RDF.
>
All of the above either provide context or qualify RDF. Most expand RDF in
the long description.
If you are going to use an acronym from a specialised field as a central
part of the package description, you should either expand or explain the
acronym.
At the absolute least, you need to provide enough context so that the
acronym won't be confused with other possible meanings. Anything less is
just begging to be misunderstood.
> I really don't see the use case here.
>
Package descriptions should as clear as possible to all users. Resource
Description Framework is plain English that all readers can understand.
They may not be familiar with the subject matter, but at least they can
understand the words that you're using. That way you avoid alienating them
with unnecessary jargon.
Andrew V.
[0]. http://en.wikipedia.org/wiki/Rdf
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
