[Debtags-devel] Good short descriptions: the protocols

[Enrico Zini]

On Sat, Nov 12, 2005 at 07:35:11PM +0100, Torsten Marek wrote:

> > tag name...). I think the short description should add some information
> > to the sole tag name.
> Okay, CORBA is still much shorter than than. But take the new package browser
> enrico posted today: the tag name is not shown, only the short description,
> which is a good thing (tm) for everybody who doesn't think in
> category::subcategory.

I would try to go towards hiding the tag names as well.  Not only
because they look scary (which is by itself a good reason), but also
because they can't be translated, while package descriptions can.

Also, I'd like to preserve the facet name into the presentation of the
tag name: else some tags become totally indistinguishable
(made-of::lang:c++, devel::lang:c++) and others risk becoming
meaningless (use::login, works-with::archive).

Keeping this in mind, having the unexpanded tags in the short
description isn't such a bad idea.  Here's an example with Italian
translations:

protocol::http
	Protocol -- HTTP
           HyperText Transport Protocol, foo bar baz...
	Protocollo -- HTTP
	   HyperText Transport Protocol, pippo pluto paperino...

protocol::corba
        Protocol -- CORBA
	   Common Object Request Broker Architecture, foo bar...
	Protocollo -- CORBA
	   Common Object Request Broker Architecture, pippo pluto...

use::editing
        Use -- Editing
	   The package is mainly used to modify something.
	Uso -- Editing
	   Il pacchetto è usato principalmente per modificare qualcosa.

works-with::3dmodel
	Works with -- 3D models
	   The package can work with 3D models.
	Lavora con -- Modelli 3D
	   Il pacchetto lavore con modelli 3D.

(In this example I'm unsure in having long description starting with
 "The package can").

> > Note that the decision made here could become a general policy for such
> > cases even outside the protocol facet. There are loads of cases:
> >       * works-with::sgml,
> >       * works-with::xml,
> >       * works-with::rss
> >       * suite::zope
> >       * web::cgi
> >       * ...

I'd think of three uses for the tag description (Justin please tell me
off for abuse of "-ation" words):

 1. Identification: telling what the tag is about, for example, giving
    the difference between CLI == Command Line Interface and CLI ==
    Common Language Infrastructure.
 2. Explanation: telling in more detail what the tag is about, so that
    one can use it efficiently in a package search or use it efficiently
    for tagging.  See for example the description of role::sw:utility
 3. Learning: teaching about this category.  This marks the difference
    between "if you don't know what this is then you don't need it" and
    "if you don't know what this is then I'll tell you", but isn't
    necessarily used for categorization.

So, when we're expanding CLI with "Command Line Interface", we're helping
people identifying the tag; however, when we're expanding Corba
with Common Object Request Broker Architecture, we're teaching people
what Corba really means, as "Corba" is definitely easier to associate a
meaning than its expansion.  Another example similar to Corba is PCMCIA:
the acronym is better understood than its expansion.

I'd say that the short description is used for identification, so it
should have the shortest form we can possibly find that can allow people
who know about the topic to recognize it.

The long description probably needs to be most focused on explaining
what the tag is for rather than teaching about the topic.  I'm unsure
how much of teaching belongs to the tag description, though.  Maybe we
could add a field "Further links" where to put links to Wikipedia
instead of replicating informations in the vocabulary.

> I think that we actually need a general policy on what belongs into the short
> description. In the role facet, we have the "sub-facet" name in parentheses, we
> might make tagging easier, but looks a bit displaced in the web interface.

Yes, I don't like that name in parentesis.  I think we could do without
it most of the times:

  works-with::text - Text
  works-with::text:docbook - Docbook text
  works-with::text:formatted - Complex text document
  works-with::text:html - HTML pages
  works-with::text:info - Documentation in Info format
  works-with::text:man - Manpages
  works-with::text:pdf - PDF Documents
  works-with::text:plain - Plain text
  works-with::text:postscript - Postscript
  works-with::text:sgml - SGML text documents
  works-with::text:tex - TeX, LaTeX and DVI
  works-with::text:unicode - Unicode text

In this case (where I tweaked the descriptions a bit), it's almost
obvious that all these short descriptions are related to Text, and the
grouping could kick in in the interaction rather than in the description
(for example, all packages with one text:* tag would also have the text
tag), or the 'text::*' tags could be shown in a submenu.


Ciao,

Enrico

--
GPG key: 1024D/797EBFAB 2000-12-05 Enrico Zini <enrico at debian.org>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
Url : http://lists.alioth.debian.org/pipermail/debtags-devel/attachments/20051114/07a3b8f4/attachment-0001.pgp