Notes: @a-kenji
-
How to improve learning situation for oneself?
- Where to look for new information?
-
@fricklerhandwerk read the How to contribute to documentation? diagram from bottom to top
- please add information you have found or move it to more appropriate places if it appears obvious
- ask @fricklerhandwerk when in doubt
- please add information you have found or move it to more appropriate places if it appears obvious
-
@fricklerhandwerk read the How to contribute to documentation? diagram from bottom to top
- Where to look for new information?
-
Better definition / template for deployment stories.
- Writing style in documentation? Especially in tutorials: Procedures, Overview (Descriptions, no explanation), Do they belong in the same document, or should they be separated?
-
@fricklerhandwerk Generally speaking there should be two types of artifacts that we maintain: Ideally reference-style documentation would live together with the code. And tutorial-style instructions should refer to the reference-style documentation.
- see nixpkgs#176557 for a recent example of how to do it very well
-
@fricklerhandwerk Generally speaking there should be two types of artifacts that we maintain: Ideally reference-style documentation would live together with the code. And tutorial-style instructions should refer to the reference-style documentation.
-
@fricklerhandwerk Possible way to get deployment stories: Pair with people and observe their painpoints, document them.
- ideal to get to know each other in the program
- ask people directly and take time when asked for
- @mat The first time trying something out is the most valuable moment, because there is no intrinsic knowledge yet.
- @mat Deployment stories should not necessarily be similar in scope, but ideally vary for the projects.
- @mat Don’t try to get the perfect example up, get some content and get a PR, so we can get useful discussions starting.
- Writing style in documentation? Especially in tutorials: Procedures, Overview (Descriptions, no explanation), Do they belong in the same document, or should they be separated?
-
How to help with documentation?
- Anything might improve the situation: Find missing stuff in wiki, change wrong commands, old examples…
- whenever you stumble over something, take some extra time to make it better for the next person which may have the same problem
- The Nix manual and the other reference material overhaul is always in demand!
- What are you working on right now? What language ecosystem. Have the nix manual open, if there is difference between your workflows, maybe it makes sense to update the wiki itself?
- A possible focus is “Nix Onboarding”, how to dampen the initial learning curve of unusual concepts.
- Explanation of the situation with Flakes
- Distinction of imperative and declarative Package management.
- Good explanation of the differences between Nix,
nixpkgs, and NixOS. - Improve, or create contribution guidelines
-
@toraritte collected notes on this: How to make it easier to contribute to the documentation
- Improve onboarding of onboarding people
-
@toraritte collected notes on this: How to make it easier to contribute to the documentation
- Proper overview of the nix ecosystem
- maybe improve awesome-nix
-
@fricklerhandwerk I find a collection of resources without much context problematic
- for instance, it does not indicate how mature or widely used a given tool is, or what exactly a piece of advice teaches the reader
- related and still undecided: what is a project in the Nix ecosystem?
- I would rather see the discoveries people can make from such a collection emerge from the regular learning process, where suggestions are placed organically with the use cases people try to solve
-
@fricklerhandwerk I find a collection of resources without much context problematic
- maybe improve awesome-nix
- Where to put ancillary content? (that is not Nix, but helps understand a specific functinality; e.g.,
fetchGitrequires knowledge about Git internals)- @fricklerhandwerk If it does not fit the manuals, put it into NixOS Wiki
- Anything might improve the situation: Find missing stuff in wiki, change wrong commands, old examples…
-
Do we have statistics of the most visited pages? Can we get them?
- @fricklerhandwerk unfortunately not. this needs some coordination, which takes time no one has left. opened an issue for tracking the discussion.
-
Collecting an overview of contributions by team leads
- anything tangible (link to your work)
- example by @toraritte from last week
- Reports required for funding organizations
- Community should have an idea of what is being worked on
- also in the hopes of motivating others to contribute.
-
General documentation effort: current focus is on improving nix.dev and it is supposed to be the current entrypoint for newcommers joining nix.
-
How to coordinate working on the docs? (avoid wasting time or pair up with folks)
-
@fricklerhandwerk Publish your intent, and start working in the open (i.e., make a PR, draft PR, Wiki stub, discourse, etc.)
- Make work visible, to minimise creating friction.
- albeit, a central place would be nice - but then again, what is “central” in the Nix community… Discourse?
- @fricklerhandwerk Pull requests (and drafts) are suitable for larger ongoing work, everything else should be a small-enough chunk not to stand around too long. Other than that, Discourse is the central place in the community.
-
@fricklerhandwerk Publish your intent, and start working in the open (i.e., make a PR, draft PR, Wiki stub, discourse, etc.)