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 [email protected] http://lists.science.uu.nl/mailman/listinfo/nix-dev
