I fully agree, and probably others too, but someone has to step up and lead that effort :)
On Wed, Nov 18, 2015 at 3:04 PM, Hajo Möller <[email protected]> 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 > [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
