[Nix-dev] Missing documentation

[Mikey Ariel]

On 16 Feb 2015, at 19:53, Ertugrul Söylemez <ertesx at gmx.de> 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
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev