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

[Justin B Rye <jbr@edlug.org.uk>]

Justin B Rye wrote:
> 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? 

I'd also be inclined to retitle this bug to something like
"[developers-reference]: explicitly deprecate verb phrase synopses",
but I'd prefer to hear from you before I do that.

By the way, just talking about "starting with a verb" isn't a safe
diagnostic, since it's possible to construct a valid noun phrase
synopsis that begins with a verb:

	dndtool - do not disturb sign generator

just as it's possible for the deprecated verb phrase format to begin
with a noun:

	fwutil - hand compile your firewall rules

The only reliable way for non-specialists to tell whether a phrase
obeys the guidelines is to slot it into the heuristic template and
see if it fits.
-- 
JBR
Ankh kak! (Ancient Egyptian blessing)