RE: [External] : Re: New optional Eshell module: em-elecslash

[Drew Adams <drew.adams@oracle.com>]

> IME, use of passive tense is not the "disease", it's a symptom.

Yes.  Or rather, an indicator/hint that something
can perhaps be improved.

> The "disease" is overly complicated sentences that make the text hard to
> understand.  Using passive tense is a good indicator that the
> structure of the text is sub-optimal and needs to be rethought.
> Trying to use active tense as much as possible in many cases leads to
> such rethinking and makes the text more clear.

+1.

> We all bump into that from time to time.  Some techniques for dealing
> with the difficulties:
> 
>   . omit some less important parts, like "the" etc.
>   . rearrange the text to make it shorter (for example, say "buffer
>     text" instead of "the text of the buffer")
>   . omit less important details from the first sentence, and describe
>     them in the following parts of the doc string

+1.

Another convention that can be limiting is to
present function parameters in order.

That too can require rewording.  In particular,
it can sometimes mean not mentioning parameters
in the first (one-line) sentence.

The first line is quite important.  It can be
used in contexts as a short description of the
object (e.g. function).  It needs to be short
and yet give a reasonable overall description.