[Nix-dev] Missing documentation

[Ertugrul Söylemez]

>> 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.

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.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 472 bytes
Desc: not available
Url : http://lists.science.uu.nl/pipermail/nix-dev/attachments/20150216/ff079021/attachment.bin