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

Bug#536889: [developers-reference]: Please add an example for the short description starting with a verb

Jens Seidel wrote:
> as described in #400970 the formulation of the short description starting
> with a verb is not clear. Chapter 6.2.2 suggests:
> "A good heuristic is that it should be possible to substitute the package
> name and synopsis into this formula:
> The package <name> provides {a,an,the,some} <synopsis>."
> Applying this to a package description as
> "display large colourful characters in text mode"
> one could guess that a 3rd person form is more suitable:
> "displays " ...

No; both are wrong and fail the heuristic.  "Display things" is a
verb phrase; "displays things" is a verb phrase; and verb phrases
don't fit the formula.  As the previous line of DevRef6.2.2 says,
what developers are meant to be using is a noun phrase (minus
articles), _not_ a verb phrase.  Of course, DevRef guidelines aren't
legally binding, so a lot of package descriptions are malformed.

Since I'm the guy who came up with the current phrasing (of a
pre-existing recommendation; see bug #516436), I'd be interested to
hear what you'd suggest as a way of communicating this more clearly.
It was already obvious that technical terms alone wouldn't work
(because they're meaningless to non-linguists); but it seems the
substitution formula doesn't work very well either.  Or does it just
need to give more examples?  Maybe examples of what _isn't_ right? 

In this specific case:

 Package: toilet
 Description: display large colourful characters in text mode

The problem with a synopsis like toilet's is that it doesn't say
what sort of thing this package is.  What's needed is a description
that makes it clear to people browsing the package repositories
whether toilet is a:
 - daemon that puts a scrolling marquee on the console
 - font-setup utility for the partially sighted
 - text banner generator using ASCII art
See?  Those are all expressed so that they do fit the formula - "The
package toilet provides a... text banner generator using ASCII art".

Oh, and if that package description came to debian-l10n-english for
review I'd also en_USify the spellings and ask "why TOIlet?"
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package

Reply to: