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

[Roger Qiu]

Can the manual be made as a gitbook with the chapters fleshed out better
and made more user friendly? One  part of the manual can be very fact
based, another part can be story based. Kind of like the difference between
documentation vs api documentation vs tutorials. I often find myself across
3 to 4 different blog posts, the arch and gentoo wiki, the nixos manual,
the wiki and github issues because the up to date relevant information is
everywhere.

There's also alot of pitfalls that's not mentioned anywhere except in
github issues.
On 19/11/2015 1:04 AM, "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/20151119/66ff7e11/attachment.html