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

[Domen Kožar]

I fully agree, and probably others too, but someone has to step up and lead
that effort :)

On Wed, Nov 18, 2015 at 3:04 PM, Hajo Möller <dasjoe at gmail.com> wrote:

> 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
>
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20151118/a1848b20/attachment.html