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!
_______________________________________________
freebsd-ports@freebsd.org mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-ports
To unsubscribe, send any mail to "freebsd-ports-unsubscr...@freebsd.org"
