Checking port option descriptions

[Warren Block]

On Fri, 16 Sep 2016, Jim Ohlstein wrote:

> Hello,
>
> On 09/16/2016 11:52 AM, Warren Block wrote:
>> Ports options ask the user to make a decision on whether to enable that
>> option.  Option descriptions are critical for this, giving the user
>> information to help them make that decision.
>> 
>> Unfortunately, what is clear to the porter is often not clear to a user.
>> The Porter's Handbook says "Do not just repeat the name", but this still
>> happens, either exactly, or with a description that adds no information.
>> 
>> For example:
>>
>>   XYZ    Enable XYZ
>> 
>> The description here adds no information. The name of the option itself
>> tells the reader that this is for enabling or disabling a feature. The
>> option asks them to make a decision, whether to enable that option or
>> not, or even just to leave it at the default, but does not give them any
>> help in making that decision. Let's improve that:
>>
>>   XYZ    Include protocols for use with XYZ servers
>> 
>> This gives the reader some additional details.
>
> "[S]ome" being the operative word here. I don't disagres with your basic 
> premise, but the truth is, at the end of the day it's up to the user to 
> understand the consequences of his decisions. If a user doesn't know what 
> 'XYZ' is, then adding 'Include protocols for use with XYZ servers' probably 
> doesn't tell him or her that much. On the other hand, if a user knows what 
> 'XYZ' is, then 'Enable XYZ' is likely enough information with which to make a 
> decision.

Certainly the user is ultimately responsible.  On the other hand, it is 
irresponsible to force the user to choose without giving what help we 
can.  Especially since we have a framework which makes that easy to do!