[Nix-dev] NixOS: How to have the best user experience

[Nicolas Pierron]

Hi Nixers,

This mail contains a few suggestions we may follow to offer the best
user experience to new users of NixOS.  Some of these points are made
after patches or IRC answers and others are just proposals.

All point are details with should / shouldn't list.  Of course, "
shouldn't " points can be used by more experimented person but new
users should not see them unless they highly express the need.  If we
cannot answer a person with these terms, then that's our work to make
it possible.

1/ Nothing to learn.

User coming on NixOS may not have any knowledge of Nix.

Simple writing rules:
- name "=" value ";"
- "{" "}"
- "[" "]"
- strings
- int
- boolean
- copy & paste

Never in configuration.nix: (neither generated nor hand written by the user)
- Nix control statements (if .. then .. else .., with ..; , let .. in .., ...)
- functions (concatStrings, ...)
- properties (mkIf, mkOverride, ...)
- operators (+, ++, //, ?, &&, ||, ...)

2/ Straight forward.

All informations in:
- The manual
- configuration.nix

Never use:
- Personal patches or branches.
- NixOS sources.
- Nixpkgs index.
- Hydra's buildfarm.
- IRC

If you have to redirect one person to extra informations, then you
have to patch the manual.

3/ Fast.

Should only see:
- Available options based on his current configuration.

Should never see:
- All options which do not have effects on the system yet.

Currently the manual never stop growing with all supported options.
This manual is useful for searches, but users are not hab to search
through huge list of options.  This is extremely bad because users
need more times to find what they should do to setup their NixOS
system.

4/ Short

Provides:
- Wisely chosen Default value.
- Abstract configuration modules & options (Sheevaplug, compaq
presario 2144EA, ...)
- Usage report (to choose default values)

Avoid:
- Tons lines to tweak you configuration.
- Complex lines to tweak you configuration. (no mkOverride in configuration.nix)


-- 
Nicolas Pierron
http://www.linkedin.com/in/nicolasbpierron - http://nbp.name/
Andrew S. Tanenbaum - Never underestimate the bandwith of a wagon full of tapes.