DOC: Overview of Nixpkgs/channels/Hydra/tests

[FRidh]

What I missed when I began using Nix and NixOS was a clear overview of
how packages, channels, Hydra, the master branch and updates to channels
relate to each other.

I've noticed I am not the only one, given the amount of times these
questions pop up.

For now I propose to include this in the Nixpkgs manual, since this
seems to be the best fit. However, I think it would be good to include
this in either a new manual, i.e., a user manual, or an 'official'
tutorial.

[FRidh]

@vcunat Here's an update to the introduction of the Nixpkgs manual.

[peti]

That number is probably more like over 30,000. Nix-env lists 13,406 builds, and there are (at least) another 12,000 packages for Haskell and 7,000 for R in the database that nix-env won't see.

[vcunat]

I'm not sure what to count. There are also a few thousand TeX packages now (hidden to nix-env). But the order would be higher than what's written here IMHO, i.e. ?0 000.

[domenkozar]

I like the docs, but we're fragmenting too much. There should be a better place to put this.

[vcunat]

Mainly, this is not shown in the nixpkgs manual or linked in any other way.

[FRidh]

Indeed, this wouldn't be visible and thus shouldn't be merged as it is. To put it in context, I wrote this after a discussion on the mailing list about the documentation format when @vcunat wrote

submit the new high-quality docs in whatever format you like best
(sounds like there will be tons of it). After reviewing the content, I
will convert them myself (to docbook) and integrate into what we have.

So, this is just about the content.

[vcunat]

I see; I've been thinking hard what to do about this, as the information in this PR does seem to be missing sorely.

I believe we need a complete re-design of documentation, maybe add some nixpkgs user manual for issues around using nixpkgs, shared by NixOS and non-NixOS (mainly darwin and other linuxes). The current nixpkgs manual is meant (mainly) for people wanting to modify nixpkgs which is a minority of its users (or will become in future).

[vcunat]

Hmm, maybe better: nix+nixpkgs user manual. Few will just use nix without our nixpkgs, and the current nix manual explains way too much above what's needed for using nix+nixpkgs.

[FRidh]

It's a really difficult topic. Maybe we should discuss this further on the mailing list.
(Do need to make clear not to go astray on implementation details like doc formats)

[vcunat]

I plan to collect my thoughts during this week and bring it up including a proposal with (tentative) new docs layout.

(Do need to make clear not to go astray on implementation details like doc formats)

Yes, I'm careful to avoid that, as you can see from #11263 (comment).

[FRidh]

@vcunat

How about...

1. Nix reference guide, as we have it now
2. NixOS reference guide as we have it now
3. Introduction to Nix, a new guide with introductions to Nix, NixOS and modules, Hydra, Haskell on Nix, Python on Nix, and so on. Each their own chapter. And an overview chapter, in which the content of this PR would fit in.
4. Nixpkgs reference guide, that describes how it can be used, documents specific modules, specific functions, specific constructs, and so on.
5. Nixpkgs contributing/style guide.

Separately we could perhaps have something with tips and tricks, although I'm not such a fan of that.

[vcunat]

I was personally thinking about creating Nix+Pkgs user's guide that should include a first-level introduction as well for anyone wanting to start with nix/nixpkgs/nixos (the nixos-specific parts would be separate, most likely).

Currently the nixpkgs manual, for example, is focused on people who want to contribute to nixpkgs, and the nix manual also seems to contain far too much to just use the stuff, etc.

[vcunat]

I forgot to add... I don't have enough time these weeks to plan/propose such big docs changes, but I hope to revisit it later, unless someone else improves the state.

[FRidh]

Yes, we need more material for users. The difficutly with Nixpkgs is of course that many users are developers, and while maybe not Nixpkgs contributors they do use Nixpkgs and need to know what is in it and how certain functions work.

Actually, a users guide that would consist of two parts, Introduction and Reference, thereby merging 3) and 4) from above seems ideal to me. That way you can at least have references to the Reference part.

What do you think about my WIP proposal at https://gist.github.com/FRidh/0fbb86fde3c4e26045a1 ?

Update:

Shortly after this message I send out an e-mail about the topic
http://www.mail-archive.com/nix-dev@lists.science.uu.nl/msg18125.html

[FRidh]

@vcunat I'v updated this PR. The content is now converted to docbook and included.

[vcunat]

This way seems good. Thanks.

Restructuring the docs is a separate question...