[Nix-dev] Real documentation, aka "Let's kill the wiki"

[Hajo Möller]

As mentioned in another thread, Rok Garbas proposed to remove the wiki
and replace it with "real documentation". I fully support this.

To follow up on this proposal I suggest we decide what real
documentation should look like, so let us reiterate his main points:

"Why do we write documentation?"
Is it just to remind ourselves about details, or also for helping the
readers reach an advanced level of understanding? It should be the both.

"There needs to be a clear definition of how documentation is written."
We already have coding conventions, but there is no clear how-to for
writing good documentation. Maybe (professional) technical writers can
chime in here?

"Documentation should teach, not tell."
As Rok said, handing somebody who is learning a new language a
dictionary would not help them learn.
It is not possible for us to get an immediate reaction to pinpoint the
exact moment our documentation becomes incomprehensible, having our
documentation follow a well-defined pattern should help here.
This also means we need to hold our users' hands, leading them
step-by-step through complex procedures instead of directly presenting
results.

"You should never tell somebody to read the source."
Even though the source code should be self-explanatory (and often is,
see the files in nixpkgs/lib for well-commented examples), having real
documentation in the form of a manual helps keep everything in the same
place. This way there can be a single location where users come to when
they are lost.

"The manual is good, but not made for beginners."
Rok suggests to have tutorials teaching the basics of Nix and NixOS.
Although I generally agree, I am not sure where to place those tutorials
and what they should cover. Should they be on people's blogs, aggregated
in the planet.nixos.org?

"Let's kill the wiki, it's not documentation but an abomination."
Unmoderated wikis tend to contain outdated or just plain wrong
information, it is then arguably better to have no documentation at all
than a wiki teaching the wrong things. Also, developers asking (possibly
misunderstanding) users to fix the wiki could lead to a scenario where
the blind lead the blind.


-- 
Regards,
Hajo Möller