cabal2nix

cabal2nix copied to clipboard

I would like to make a contribution to the haskell4nix documentation, but I wanted to let you all know in advance in case anyone is currently working on something like this, or wants to suggest a different approach.

@peti @raboof @Mathnerd314 @stevana @Anton-Latukha

In nixpkgs-users-guide.rst, I plan to describe a simpler approach for beginners first. The material that is currently there will remain, but will be in a separate subsection. The resulting structure will be:

. . .
How to create a development environment
    A simple approach for beginners
        I will adapt some of the material from my tutorial here: 
        https://github.com/mhwombat/nix-for-numbskulls/blob/main/Haskell/ss-haskell-dev.md   
    A more customisable approach
        How to install a compiler
        How to install a compiler with libraries
        How to install a compiler with libraries, hoogle and documentation indexes
        How to install haskell-language-server
        How to make haskell-language-server find a GHC from nix-shell
        How to build a Haskell project using Stack
        How to create ad hoc environments for nix-shell

I think if you're going to add a tutorial it's worth considering the structure of the documentation. I've found https://diataxis.fr/ recently. We don't have to follow it exactly, but a tutorial is a separate "mode" from the how-to stuff that's in the user guide, hence should be in a different page.

Also, the PR doesn't really have an explanation of how developPackage relates to the other functions (ghcWithPackages,/ghcWithHoogle). There's some of that in the markdown file.

So IMHO it would be better if you just ran https://github.com/mhwombat/nix-for-numbskulls/blob/main/Haskell/ss-haskell-dev.md through pandoc and added it as a tutorial page.

Also, the PR doesn't really have an explanation of how developPackage relates to the other functions (ghcWithPackages,/ghcWithHoogle). There's some of that in the markdown file.

Nor should it. Any question/explanation/solution/answer is incomplete even just taking Gödel's incompleteness (which applies to any language or solution), & we must remember that. The question of "what is not there" is particularly endless one.

The {developPackage, ghcWithPackages, ghcWithHoogle} should be better explained in the Nixpkgs documentation in the first place, since it is where everyone come to look for their documentation & there indeed the better documentation needed, that is outside of the scope of the PR.

& we must remember that mhwombat was not required to do it in the first place & there was a complete nothingness before, where now is his explanation, to support people.

I share a view on documentation is that it is better to take it & say thank you then to nitpick it much. It would be great if documentation imrovements would've been easy to submit & merge. Then maybe we managed to raised the culture of documentation, and then got better documentation everywhere. It is really just a formed by Ward Cunningham principles on which wikis are designed on.

The contribution to documentation is also a nice space to start contributing into the project, & contributing as you learn the topic, that is also why the documentation contributions should be easy process to create a culture of collaboration.

Maintainers are perfectly apt to take the merged information & make a tutorial from it. The tutorial & its form seems like more a decigion to be made by them then a requirement on a volunteering contributor.

There's ongoing work (which has stalled a bit for the moment) to migrate the haskell4nix manual to the nixpkgs manual in content and overhaul the structure as well as adding some missing bits: https://github.com/NixOS/nixpkgs/pull/126674

Thus docs are in limbo a bit and I'm unsure if it's the best idea to start any major work on the docs in this repo.

For now at least, I plan to continue to maintain my original tutorial separately. So while the location and structure of the haskell4nix documentation is in flux, I could replace the section I added with a link to my original tutorial. It might also be worth adding a link to this post on Discourse which outlines some logical options for developers to consider once they're comfortable with the basics.