Update documentation to reflect changes / additions

[doughsay]

[Omikhleia]

In progress in a dedicated branch.

• For now, place to track changes and keep in sync.
• Later one, possibly restructure the docs (e.g. split the tutorial and reference guide in programming doc).

[Omikhleia]

As of June 2018, up-to-date further to PR #185 - Leaving the issue open not to forget future updates.