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

[Karsten Gebbert]

Hajo Möller <dasjoe at gmail.com> writes:

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

I think that it would be good to loosely decide on the sections a good
manual/documentation should consist of. This might help structuring the effort
and break up tasks in meaningful chunks.

I guess the gold standard in FLOSS OS documentation is the Arch Wiki (kind of),
and it would be good to approach the task with its quality and comprehensiveness
as the long-term goal.

>From the top of my head, there are multiple aspects to it:

* Cookbook (how do I do XYZ?) e.g.
  - setting up a Desktop environment
  - setting up ...
  - setting up a development environment
  - detailed guides on developing with in language XYZ
  - overriding/customizing packages
  - ....
* nix-* command reference (man pages would probably already suffice)
* nixpkgs & library (w/ inline docs)
  - modules
  - contributors guide
  - function reference? 
* nix, the language
  - reference manual
  - useful snippets?

So, if there is an effort to aggregate information in one place, we could split
up the task according to such a list of sections and work more or less
independently in branches.

Best,

karsten