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

[Nikki A.]

Perhaps this could work even nicer with literate programming. Source 
files could be then exported as manual chapters or extra reference, and 
the source code displayed next to text would fill gaps for curious 
readers without having to search github or download a whole nixpkgs 
repository. That would be even more awesome if some automatic two-way 
hyperlinking with usage sites could be implemented, as in a code browser 
- but I don't know if tools that good exist.

PS. Hi, this is my first message here; I'm just learning and playing 
with Nix and passing by in search for more info :)

On 18.11.2015 16:00, Augustin Borsu wrote:
> What about having a documentation field in pkgs that allows for markdown?
> Can't get closer to the code than that.
>
> 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