New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Adding a simpler dev workflow for Nix beginners #514
Comments
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. |
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 & we must remember that 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: NixOS/nixpkgs#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. |
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:The text was updated successfully, but these errors were encountered: