On Fri, Nov 12, 2004 at 03:34:45PM +0100, Frank Küster wrote: > Jonathan McDowell <[EMAIL PROTECTED]> schrieb: > > On Fri, Nov 12, 2004 at 12:17:20PM +0100, Frank Küster wrote: > >> To my taste, this description contains too many abbreviations, and is > >> only understandable for someone who already knows what they mean. Please > >> follow the general guidelines for descriptions, > > "The package description should be written for the average likely user" > > > > The average likely user should know what L2TP is and understand the > > LNSes role in this. > No, I don't think so. I think that "the average likely user" is meant > to be an average user of Debian, not the user of the package. This is > logical, because the purpose of the description is to allow a user to > decide whether he *is* the target user of the package.
If the user doesn't understand the package description, is it not reasonable to assume they'll work out it's probably not for them? If I went searching for something and found a handful of packages, some of which had many terms I didn't understand while the others did, I'd assume that some of the packages weren't appropriate to what I wanted. Must we dumb everything down to the lowest common denominator rather than assuming our users have some level of intellegence? > Did you read the complete paragraph? It explains its intention with an > example: > > ,---- > | Avoid referring to other applications or frameworks that the user > | might not be familiar with ? "GNOME" or "KDE" is fine, since users are > | probably familiar with these terms, but "GTK+" is probably not. Try > | not to assume any knowledge at all. If you must use technical terms, > | introduce them. > `---- > > If GTK+ is not acceptable, how can l2tpd, l2tp and lns be? They could, > if you _first_ state clearly that the package is only aimed at people > experienced in some type of network setup. Any user who wants to do > something about her dialup connection and enters "apt-cache search ppp" > should immediately know whether the package might be useful (perhaps > after some or a lot of reading) or whether it is about something > different. I would argue that the majority of people using GTK+ apps are going to be wanting pointy clicky front ends and thus not necessarily know or care what GTK+ is. Would you be satisfied with "This package is not intended for users who want to setup a local dialup or similar connection; you probably want the ppp package instead." as the first paragraph of the description? Or perhaps "This package is aimed at those who need to terminate a large number of L2TP sessions; if you're a home user you probably want the ppp package". > > (And the only abbreviations I count in the description are L2TP [which > > gets expanded], LNS, PPP and ISP.) > That's about 3 to 4 too much. Generally, because of good style, > not because they are unfamiliar to me. I'm sorry, I disagree. PPP and ISP are commonly used terms and L2TP/LNS should be familiar to the users of the package. J. -- Revd. Jonathan McDowell, ULC | Don't be a stranger.
