Add a meta.instructions field

[tobiasBora]

Right now (as far as I know), there is no way to properly document the instructions to follow in order to get started with a package. These instructions might be arbitrary, but the main application I have in mind concern stuff to add in configuration.nix (or equivalent command for non-NixOs devices) to allow the program to run smoothly, or the instructions to follow to get started (for instance, if you install a driver, you might need to start a program to get the driver running).

Level 1

The simpler thing to implement could be to add a field meta.instructions containing arbitrary instructions. For instance when installing a driver, one often needs to also add the package to services.udev.packages so that udev is properly configured. So I would love to document a driver using something like:

meta: {
  instructions: "To properly run this driver, make sure to either run it as root, or, better, if you run NixOs, properly configure udev by adding in your `configuration.nix` a line `services.udev.packages = [ thisDriver ]`.  If you do not run NixOs, then please do FOO. Then, you can start the driver by starting the program `vktablet` either in command-line or by clicking the corresponding icon in your launcher.";
}

This information should be displayed when installing a program for the first time, and this instructions message should also be displayed in https://search.nixos.org.

Level 2

Then, it could also be nice to add more computer-parsable fields (but this needs more time to think about what is needed and what is not), to help the system to automatically flag a warning message if the user improperly configured a program. For instance, it could be interesting to add a field like:

meta.should-be-in-udev: [ self ];

in order to print a warning message if the program is installed without being added in udev. One could also add some fields pointing to the nix documentation, like:

meta: {
  nixpkgs-documentation: [
    "https://nixos.org/manual/nixpkgs/stable/#nextcloud"
    "https://nixos.wiki/wiki/Nextcloud"
   ];
}

to help the user getting started, or possibly add some instructions to say that the program should be used inside a module:

meta: {
  should-be-installed-via-module: [ my-module ]; # prints a warning at install time if the package is installed while the corresponding modules are not configured
   minimal-module-configuration: {
    service.my-module = {
      enable = true;
    };
  };
}

While the exact set of meta-attribute to provide might require a bit of time to choose appropriately, should we agree that instructions could be used for generic human-readable instructions, and start to print them at install time and in search.nixos.org/?

[elijahimmer]

I think that a fair number of use cases for this should just be other options in the module to enable it instead of telling them to go and do something else, that just feels against the ideas of making it declarative.
Yet this cannot/should not be done for some things, but I think putting instructions in it wouldn't be the best idea.
There could be a tips field or something like that that just gives some small information, but I don't think it is a good idea to basically maintain a wiki in the modules themselves.
(to me even the tips field feels like it should just be a comment in the enabled field)

[tobiasBora]

What do you mean by other options in the module? My recommendation would be to target the package directly, not the module (a module might not even exist for this package).

Then, I agree that the instructions should not be too large… yet I still believe that it would be useful for several reasons. First, nixpkgs wants the wiki to be as small as possible, and recommends that all documentation should be moved to the manual and removed from the wiki (I don't really agree with this policy, as Arch managed to show that a wiki can be extremely complete and more helpful than a manual… but it is another topic). But adding an entry in the manual has two issues:

1. First, I would feel quite bad to add an entry in the manual for any small package in nixpkgs. Do we expect a new entry in the manual for any single package that must be added in udev? (that's a real question)
2. Even if we document any single package in the manual, the manual is surprisingly extremely hard to discover. For instance, if you type in google "nixpkgs nextcloud", there is not even a single link (at least in the first page) pointing to the manual, while the manual does contain an entry https://nixos.org/manual/nixos/stable/#module-services-nextcloud for nextcloud. I guess that maintaining a single page containing all the nixpkgs manual is a fairly bad idea when it comes to SSO, but it is another question. My hope is that the documentation (or link to documentation) should appear at least in https://search.nixos.org/packages and in the first results of any search engine. For now, the instructions in https://search.nixos.org/packages are quite misleading, as most of the time people want to install the module and not the package (but they might not even have the reflex to check if a module exists):

Also, printing the instructions when installing the software is useful to explain the user why they are doing something that is unlikely to work, and what they should do instead to get it working (personally, my first reflex when installing a software is to… install it, as it is what anyone would do on a standard distribution, not trying to search in the manual if there is something written about it).
4. The fact that the documentation for the module is located in a different file than the derivation makes it also harder to discover, and write (you need to go to another folder, create a new file, remember the DocBook XML syntax, check if it compiles using some magic validation tools… way more complicating that adding a basic meta line).

So at least adding in the meta a link to the documentation in the manual would be a first step towards discoverability of documentation, if there is a clear policy saying that any package that uses udev should get a new entry in the manual.

Also, I don't quite agree with comment in a source-code is of no use to a user since users are not expecting to read the source code.

[FliegendeWurst]

This information should be displayed when installing a program for the first time

When is a program installed for the first time? The first time a store path for it is realized?

[tobiasBora]

When is a program installed for the first time? The first time a store path for it is realized?

Ahah, that's a good question. So first, it might be a good idea to define different levels of verbosity (some people might want to disable all together these instructions), e.g. based on some environment variables/command flags. Since I’m not aware of all the internals of nix, I might also not be the best one to give the best answer here.

So the first answer might be "whatever is easier to implement". Then, to go into more details, the problem of using the creation of a store path is that it is dependent on garbage collection (or maybe "realized" means something different for you than created? I’m not so sure about the actual terms), and if user A already installed the package, user B might not get the info (ok, this is maybe not so important after all). But if nix provides a way to check the list of "reachable" store paths (like "in the path"), then one might just be able to do a diff of the reachable store paths before and after running the command, and print the appropriate warning messages… One can also only make it work for imperative commands like nix-shell -p foo should always print the message of foo if it exists and nothing else… I guess this depends a lot on the simplicity of the implementation, efficiency…

[FliegendeWurst]

(or maybe "realized" means something different for you than created? I’m not so sure about the actual terms)

To "realize a store path" means to either fetch it from a substituter (cache.nixos.org) or build it (Nix reference).

the problem of using the creation of a store path is that it is dependent on garbage collection

Indeed it is. If the user collects garbage between nix-shell runs, the same package would be installed "for the first time" again.

user A already installed the package, user B might not get the info (ok, this is maybe not so important after all)

I suspect most NixOS installations are effectively single-user. Or at least the NixOS installations where this proposed feature would be useful.

One can also only make it work for imperative commands like nix-shell -p foo should always print the message of foo if it exists and nothing else…

That and nixos-rebuild with the package in systemPackages (if not present in earlier generations) would be the two major use cases I think.

[elijahimmer]

What do you mean by other options in the module? My recommendation would be to target the package directly, not the module (a module might not even exist for this package).
I misunderstood you there, a little, I thought you were talking about a module for it.

I also agree that searching the manual isn't the best, but more often then not wikis fall behind and are hard to maintain, the arch wiki being one of them that do work well.

Yet I am not sure this is the correct solution. This can be useful if limited to something like adding to udev, but udev is only one of the few options things that would be an instruction. The issue is that you would be maintaining not just a manual that gives this information, but it would also be in the code. Anytime you state something twice, there will be times when one of them is out of sync, and that is one of the reasons for not wanting to maintain a wiki as well as a manual.

I don't think that it is really an issue with needing more data on the package, as the manual has the information (or atleast should), but maybe adding manual links or snips to the nixpkgs search when you click on a package, as that has the same effect you are looking for while not adding multiple sources of information.

It is not an issue of lack of information (as it should be int he manual), but of lack of convenience which I think is the problem.

I could not think of other cases for instructions that would be useful, and should not be in the manual (tell me if you can think of any).