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:
pgpuvgSOct0VX.pgp
Description: PGP signature