On Fri, 16 Sep 2016, Jim Ohlstein wrote:


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!
freebsd-ports@freebsd.org mailing list
To unsubscribe, send any mail to "freebsd-ports-unsubscr...@freebsd.org"

Reply via email to