You have to think about the audience. In general following should cover us:
- tutorial (how do I get quickly update to date on X topic) - user guide (how does a specific feature work) - reference (functions and what they do) Currently that's all bundled throughout the manual (and wiki). Domen On Wed, Nov 18, 2015 at 5:01 PM, Karsten Gebbert <[email protected]> wrote: > Hajo Möller <[email protected]> writes: > > > 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. > > I think that it would be good to loosely decide on the sections a good > manual/documentation should consist of. This might help structuring the > effort > and break up tasks in meaningful chunks. > > I guess the gold standard in FLOSS OS documentation is the Arch Wiki (kind > of), > and it would be good to approach the task with its quality and > comprehensiveness > as the long-term goal. > > From the top of my head, there are multiple aspects to it: > > * Cookbook (how do I do XYZ?) e.g. > - setting up a Desktop environment > - setting up ... > - setting up a development environment > - detailed guides on developing with in language XYZ > - overriding/customizing packages > - .... > * nix-* command reference (man pages would probably already suffice) > * nixpkgs & library (w/ inline docs) > - modules > - contributors guide > - function reference? > * nix, the language > - reference manual > - useful snippets? > > So, if there is an effort to aggregate information in one place, we could > split > up the task according to such a list of sections and work more or less > independently in branches. > > Best, > > karsten > _______________________________________________ > 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
