On 18 nov. 2015, at 16:00, Augustin Borsu <[email protected]> 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 > [email protected] > http://lists.science.uu.nl/mailman/listinfo/nix-dev _______________________________________________ nix-dev mailing list [email protected] http://lists.science.uu.nl/mailman/listinfo/nix-dev
