[Nix-dev] Redesign of documentation

[Freddy Rietdijk]

Hi Nixers,

Since NixCon last year UX and documentation are in the spotlight, and
especially since the Wiki has gone to read-only there seems to be even more
pressure to come up with a good solution to the documentation challenge.

I would like to bring up a discussion on what type of documentation we
need, and what the requirements are, mostly regarding content. Let's NOT
discuss implementations and formats at this point. That's something for
later.

Currently the following guides exist:

   1. Nix Package Manager guide <http://nixos.org/nix/manual/>
   2. NixOS manual <http://nixos.org/nixos/manual/>
   3. Nixpkgs Contributors guide <http://nixos.org/nixpkgs/manual/>

as well as a (mostly outdated) read-only wiki (and documentation for Hydra,
NixOps and Disnix but I think we can leave that out of this discussion).

What clearly is missing is introductory material. What kind of introductory
material do we need? And what other type of documentation do we need? Also,
who do we want to address with the documentation? Furthermore, how do we
keep the quality high? Contributions to the guides are currently mostly
peer-reviewed since they go via GitHub.


Now, let's move on to my proposal. I propose we create the following guides

   1. Nix Package Manager guide <http://nixos.org/nix/manual/>
   2. NixOS manua <http://nixos.org/nixos/manual/>l
   3. Nix user guide
   4. Nixpkgs contributor guide

where the Nix user guide is a guide containing both introductory material
and reference material

   - Introduction to
      - Nix ecosystem <https://github.com/NixOS/nixpkgs/pull/11263/files>
      - Nix package manager
      - Nixpkgs
         - Nixpkgs Hydra
      - NixOS
      - Hydra (NOT https://hydra.nixos.org.)
      - Python on Nix
      <http://python-on-nix.readthedocs.org/en/latest/tutorial.html>
      - Haskell on Nix
      - ...
   - Reference
      - Modules
      - Python
         - buildPythonPackage
      - Haskell
      - ...

and the Nixpkgs contributor guide would then only contain details about
Nixpkgs style and how to contribute. Furthermore, I can imagine a third
part with How To's could be added to the Nix user guide.

I think we need to keep peer-review to keep the quality high, and I think
the barrier for contributing to guides 3) and 4) should be sufficiently low
to hopefully attract more Nixpkgs contributors.

So, that's my idea about the documentation. What are your views about this
issue and the proposal? And remember, no talking about
implementations/formats just yet!

Kind regards,

Freddy
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.science.uu.nl/pipermail/nix-dev/attachments/20160215/c2893093/attachment.html