[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#108416: Format of short description should be mandated



On Sun, Aug 19, 2001 at 12:04:08PM -0700, Chris Waters wrote:
> That wasn't addressed to me, but my reaction is the same as it was to
> the original proposal: this doesn't belong in policy.  It belongs in
> dev-ref or the packaging manual, or some similar set of guidelines for
> maintainers.

I yield on the policy point, as long as we can have some language in the
Policy Manual that directs maintainers to look at the Developers'
Reference for guidelines on writing package descriptions.

> > * typically be written in a form that completes the following sentence:
> >    "<foo> is a package which provides (a/an)..."
> 
> The word "typically" reveals the flaw here, I think.  "It should be
> unless it shouldn't be."

It's not quite that vague.  "Typically" indicates that at the least the
majority of packages can be described thus.  Do you disagree.

> > * expand acronyms [...]
[...]
> Counter-example: a package named "httpd" shouldn't necessarily have to
> exand "Hyper Text Transfer Protocol Daemon" in the one-liner.  We
> know.

I find this assertion in tension with the one you make later that "the
one line description should be targetted at people who _don't_ have any
idea what the package is."  Why would such people know what "HTTP"
stands for?

I think "httpd" would be a lousy name for a package, given that we have
more than one such tool in Debian, but if there were one called
"xtifr-httpd", I don't think "Chris Waters' Hypertext Transfer Protocol
Daemon" would be a bad short description.

> And sometimes the expansion of an acronym is a humorous
> afterthought: "Little Instructive New Unixlike Xystem"  :-)
> 
> > * not attempt to explain or describe things to the user that he or she
> >    would most likely already know if he or she wanted to install it
> >    (For instance, most people who care anything about python or perl
> >    packages know that these are scripting languages [...]
> 
> Here I strongly disagree.  I think the one line description should be
> targetted at people who _don't_ have any idea what the package is.

And I think there are cases where you simply can't educate people
sufficiently in 80 characters to enable them to make an informed
decision.

In Debian, there are packages that are typically installed by completely
novice end users; there are packages typically installed by Unix "power
users"; there are packages typically installed by experienced sysadmins;
there are packages typically installed by software developers.  I think
short package descriptions in particular need to be appropriate for the
packages most characterstic audience.

I simply don't think there is a way in 80 characters to explain, for
example, an Emacs major mode package to someone who doesn't even know
exactly what is meant by "editor", let alone someone who doesn't know
what Emacs is, or that it is far more than just a text editor.

> > [should not] refer to the names of other packages, protocols, [etc.]
> > in their canonical forms.
> 
> A) I think this is backwards (typo, no doubt)

Yes, it was a typo.

> (Plus, I loathe "l33t" mixed-case names
> like PostScript and NeXT, and I don't care if it's canonical or not!)

Some of these terms are trademarked and we could get into trouble for
misspelling or mis-casing them.  I agree that studly caps or marketroid
caps are often silly and aggravating, but if we refer to such things
correctly (according to their coiners) and consistently, we help out our
users to do further independent research (say, Web searches), if they're
so inclined.

That said, I think there are cases like "NeXTSTEP" where the "canonical"
casing has changed many times, and everyone is out to sea if they dare
do a case-sensitive search.  :)  I do think this is the exception, not
the rule, however,

> Furthermore, what about things like "MUA"?  Arguable a canonical form,
> but I don't think it belongs in a short description.

I would regard my goal of acronym expansion as secondary to the one
where we do our best to explain a package to its target audience.  "Mail
User Agent" is a fairly sophisticated concept for the average email user
(most of whom aren't on Unix systems) these days.

> > [should not] use indefinite articles where not necessary.
> 
> Yuck.  I'm not even sure this belongs in guidelines.

I think they should be among the first things dropped if you're hitting
the length limit.  Again, short descriptions aren't English sentences
and don't need to follow full English syntax rules.

> > [should not] use abbreviations
> 
> Piffle!  I'm not going to spell out "etcetera".

I would agree with that, but more to the point I don't think the term
"etc." should be in a package's short description in either abbreviated
or expanded form.

> > [must not] be identical to the short description of another package.
> 
> I think that _related_ packages should not have identical short
> descriptions (e.g. gcc, xemacs), but if two unrelated packages end up
> with identical short descriptions, I'm not sure it'll kill us.
> (e.g. "graphical mail reader using GTK+ toolkit".)

I continue to think it is pretty important to throw users a bone, and
help them distinguish packages based on short description alone.  Please
consider that, given the fact that we have something like 6000 packages
now, the short description is all that many users will *ever* see of a
package.  User interfaces to the packaging system are under tremendous
pressure to provide a huge amount of information in a small space,
simply due to our package count.

-- 
G. Branden Robinson                |       The key to being a Southern
Debian GNU/Linux                   |       Baptist: It ain't a sin if you
branden@debian.org                 |       don't get caught.
http://people.debian.org/~branden/ |       -- Anthony Davidson

Attachment: pgp81oIyfZK8g.pgp
Description: PGP signature


Reply to: