[Nix-dev] Missing documentation

[Ertugrul Söylemez]

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

Apparently we never disagreed.  We just failed to communicate our
notions properly. =)

One thing to note is that some functionality is genuinely unsafe, but
sometimes still useful to users doing less obvious, experimental or
innovative things.  There is nothing wrong with adding big warning signs
to the documentation in the form of:  "This is an unsafe operation that
can violate assumptions X and Y.  Make sure you understand how to apply
it safely before use!".

Sometimes there are use cases that the developers simply did not
anticipate.  This is actually quite common.  For example the `--set`
flag to `nix-env` should definitely be documented, because it is both
safe and useful when you do more with environments than managing
user-specific package sets.

If you follow this line of thought to its conclusion, then the set of
interfaces is really a union of safe (assumptions-preserving) and unsafe
(potentially assumptions-violating) interfaces.  The notion of an
"internal" interface is informal and more often than not ill-defined.  I
believe that all interfaces should be fully exposed and documented, but
the unsafe ones should carry a warning sign along with the rules you
need to follow to preserve the assumptions, i.e. how to use unsafe
interfaces safely.
-------------- 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/20150217/07a13cf6/attachment.bin