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

[deCube.net | Danny Wilson]

On 18 nov. 2015, at 16:00, Augustin Borsu <augustin at sagacify.com> wrote:

> What about having a documentation field in pkgs that allows for markdown?
> Can't get closer to the code than that.


This.
Documentation that’s seperated from code always rots.  Even when you hire technical writers...

Related talk from a Technical writer about how Google fixed their docs:  https://youtu.be/EnB8GtPuauw?t=6m18s

> 
> Also generating an html doc of all the options of a package,
> their default value and maybe a comment by the author of the package
> and an example config would go a loooong way.
> 
> Le 18/11/15 15:04, Hajo Möller a écrit :
>> 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.
>> 
>> 
> 
> _______________________________________________
> nix-dev mailing list
> nix-dev at lists.science.uu.nl
> http://lists.science.uu.nl/mailman/listinfo/nix-dev