On 16 Feb 2015, at 19:53, Ertugrul Söylemez <[email protected]> wrote:
>>> I believe everything should be documented at least in a technical
>>> manual. But there is nothing wrong with putting a note there:
>>> "Regular users should not need to use this command."
>>
>> I wouldn't be in such a hurry to document things in this manner ,
>> because the basic assumption is "if it's documented then it's
>> supported and we welcome users to use it", and how would you
>> differentiate between regular and advanced users anyway?
>>
>> Of course you should introduce the feature or functionality with the
>> use-case that it's aimed at (i.e. Why do I need this?), but
>> documenting something and then disclaimering it with "but actually you
>> don't really want to use this coz it's risky" is usually just an
>> invitation for mayhem.
>>
>> Bottom line IMHO - either you educate users with the correct
>> information and then trust them to use the feature responsibly, or you
>> don't expose it.
>
> That doesn't seem to be a coherent argument. Would you suggest that the
> `-f` option to `rm` should not be documented? Would you deny access to
> the manual of `dd` or `sgdisk` while being root? You can seriously
> break stuff with those even worse than with any Nix command.
>
On the contrary, of course it should be documented and users should be educated
as to exactly what it can do and how to use it responsibly (as in not out of
scope). But I wouldn't add a note to the extent that "hey if you're stupid then
don't even bother with this option because you might break the interwebz", like
you're suggesting.
Limitations and warnings are important, but they need to be phrased in a way
that describes examples of when not to use a feature, instead of being evasive
and saying that you need to be *this* smart to use it.
In some software products, there are some internal tools or scripts that should
not be documented because they're not supposed to be used except by support
engineers. So those shouldn't be documented because we don't want the users to
be encouraged to use them, and they're not expected to be supported.
> Software should be fully documented. If you don't know where the line
> between "regular users" and "advanced users" is, don't draw one in the
> first place. Chances are the line doesn't exist and you're just trying
> to patronise your users. I hate software that patronises me.
Umm, this is kinda the point that I was making, you were the one who suggested
to write that "regular users" should use this feature, so I explained that you
can't differentiate between regular and advanced users to you need to treat all
users equally and just document the feature in a clear and straightforward way.
> _______________________________________________
> nix-dev mailing list
> [email protected]
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
_______________________________________________
nix-dev mailing list
[email protected]
http://lists.science.uu.nl/mailman/listinfo/nix-dev
