NixOS
add outline to contribution guide
we need an easily accessible place to guide contributors and their ideas. here is one way to do it.
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/super-simple-haskell-development-with-nix/14287/4
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/pinning-nixpkgs-in-documentation-examples/20749/4
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2022-08-25-documentation-team-meeting-notes-8/21241/1
In addition to my usability tests, recent scans through Discourse revealed that beginners consistently ask the following questions:
- How is Nix different from Docker?
- What are flakes good for, should you learn to use them?
- When should you use home-manager?
- How do you pick a specific package version?
- How to set up Vim?
Answers to these questions should be one of the first documentation items to find. We mostly have them already, partially, somewhere.
@NixOS/documentation-team I had at least three conversations with Nix beginners who found this kind of overview helpful to get some orientation and set expectations. Therefore I would like to get something out there at all that we can work with and pass around.
@domenkozar I really liked your idea of linking the outline directly to articles xor pre-made issues to measure demand. But I don't want to get into these details yet, because it would require setting up a Mermaid renderer and all kinds of things to really make good use of it.
What I'm most concerned about right now is display size. Maybe we would need multiple diagrams to navigate between.
I've recently seen the talk Let’s Tell a Story: Scenario-Based Documentation, where the speaker shows examples of a complex task they were documenting, and on every large step there was a roadmap diagram with the current step highlighted.
For example, the command-line oriented section could be introduced by expanding only the relevant block:
flowchart TB
subgraph first-steps[run any program]
direction BT
run[ad hoc environments]
findpkgs[find packages]
scripts[reproducible scripts]
gc[garbage collection]
end
install[install Nix] --> first-steps
first-steps --> lang[Nix language] & imperative[imperative package management]
lang --> declarative[declarative environments]
declarative --> configuration[declarative configuration management] & pkgs[declarative package management]
configuration --> dev[software development lifecycle]
pkgs --> dev
Eventually we may even auto-generate this from contents, but this seems like a lot of setup for not a lot of material at the moment.
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/2023-03-02-documentation-team-meeting-notes-30/25971/1
This pull request has been mentioned on NixOS Discourse. There might be relevant details there:
https://discourse.nixos.org/t/this-month-in-nix-docs-1-march-2023/26913/1