Agenda
- decide on new time for work meeting
- updates
- backlog grooming
Updates
-
@zmitchell: made some progress on moving towards Diataxis, see also Learning Journey Meeting #3 Notes
- showing a local draft
- Not sure about categorization
-
@fricklerhandwerk: Don’t have to do everything at once, let’s incrementally improve the structure
-
@zmitchell: “Recipes” instead of How-to guides
- Start of a learning journey is there in First Steps, pretty linear, hard part is everything else
-
@fricklerhandwerk: FAQ should go under Recipes.
- General strategy should be: What’s the smallest non-controversial change we can implement now, pulling apart larger questions.
-
@infinisil: introduced a subgroup field to the project board that now allows assigning issues to the learning journey working group. Also a priority field, not used for anything yet though.
-
@hsjobeki: Looking for feedback for RFC 145
- Still looking for shepherds
-
@fricklerhandwerk: anybody here interested?
-
@hsjobeki: brief introduction to the RFC
-
@fricklerhandwerk: Would like to delegate to the not-yet-existent doc infrastructure working group
- Consensus: Let’s set aside some time towards the end of the meeting to discuss it
- Great task: Introduction to the module system
- relates to module system: Improve error messages around faulty imports by roberth · Pull Request #197547 · NixOS/nixpkgs · GitHub
-
@infinisil: I could do this, know a lot about it and had a talk doing exactly this: GitHub - tweag/summer-of-nix-modules: Incremental module system buildup for Summer of Nix
-
@spacekookie: Can help, also know a lot about modules
-
@pennae: There is https://nixos.org/manual/nixos/stable/index.html#sec-writing-modules, a bit more specific to NixOS, should be updated and moved to Nixpkgs manual
-
@fricklerhandwerk: Trying to break down actionable tasks. What Diataxis doc type should the first step be about?
-
@zmitchell: Should maybe be put into nix.dev instead
-
@infinisil: Infrastructure question, write docs next to source
-
@infinisil: let’s start with reference docs in the Nixpkgs manual, then we can write tutorials easier
-
@spacekookie: With some use-case coverage we inevitable cover docs most relevant to users. Maybe slightly contrived examples showing how the module system works
-
@fricklerhandwerk: That’s current state. We need to tear it apart more, but we’re simply lacking good explanation for a non-obvious mechanism.
-
@infinisil: Let’s not discuss this much further here, the ones who can write the docs can go with the flow. I’d start with reference docs, then write tutorials with those
-
@spacekookie: And I could start with some explanation-type docs, also looking at the nixos wiki page
-
@zmitchell: Where should explanation go?
-
@hsjobeki: Why are the current docs not on nix.dev?
-
@fricklerhandwerk: The idea is for manuals to be purely reference, nix.dev all other types of docs
-
@pennae: Need to take care of versioning for the manuals on nix.dev
-
@fricklerhandwerk: Very important but orthogonal issue. Just need it in one place to maintain them somehow
-
@hsjobeki: Could build manuals on nix.dev so we can reference them
-
@infinisil: Infrastructure question again
-
@fricklerhandwerk: Let’s analyze docs first
-
@pennae: Probably shouldn’t rip out the section, users installing NixOS need it
-
@fricklerhandwerk: Yes, happy path should be in a guide, link to full reference from there
-
@infinisil: Let’s link to nix.dev from the removed section
-
@fricklerhandwerk: If we have versioned manuals this shouldn’t be a problem. References shouldn’t know about the tutorials or link to them.
-
@zmitchell: Agree that reference manuals should only have inbound links
New meeting time
- 16:00 CEST Monday and Thursday
RFC 145
- https://github.com/NixOS/rfcs/pull/145
-
@hsjobeki:
- Motivation: Want to differentiate between regular comments and doc comments, maybe have native Nix support in the future
- Idea: Use markdown within the comment
- Questions:
- How to make the distinction?
- What the rules should be inside?
-
@infinisil: Why
## over /** */`?
-
@fricklerhandwerk:
nixdoc supports argument documentation which is single-line
-
@infinisil: Anti-feature IMO
-
@pennae: Argument docs how Hackage does it
-
@infinisil: Haskell has types to associate docs to, we don’t have that in Nix
- we’d have to add documentation to the implementation, which doesn’t really work
- e.g.
{ foo, ...}@args: mkDerivation args can’t properly get documentation for all arguments
-
@fricklerhandwerk: Most important task for the RFC: What problem we want to solve, which questions there are, how they can be answered, weighing the options
-
@pennae: Maybe start with type description language
-
@infinisil: We can incrementally make it stricter, first doc comments with freeform types, then strict types
-
@fricklerhandwerk: Incremental is good, we can even leave the markdown entirely freeform
-
@hsjobeki: Reserving headers for the future sounds useful
-
@fricklerhandwerk: Good patterns emerge from people using it
- We already have patterns for types and examples
-
@hsjobeki: Reserve
# Arguments?
-
@fricklerhandwerk: No pattern for that yet, should remove the section on reserved headers
-
@infinisil: Future work: Using the module system to render the type
-
@fricklerhandwerk: Then the type would be outside the doc comment
-
@pennae: Currently markdown would break the manual, also we need IDs
-
@fricklerhandwerk: Should be doable in nixdoc, might make it easier
-
@pennae: Actually not that trivial
-
@infinisil: Implementation detail, not very relevant for the RFC
-
@fricklerhandwerk: Should be noted in the RFC
-
@infinisil: Maybe the markdown should be very restricted at first.
- It’s easier to first introduce a new feature with strictness, then make it less strict as time goes on
- Discussion about whether section headers and contents should be restricted
- (didn’t take notes for a while)
- Outcomes:
- free-form documentation comment, type annotation, and examples are distinct data structures
- should define represenation and semantics separately, not lump together in a markdown comment
- type annotation should probably instead introduced to the Nix language in one way or another
- examples should be structured data, too, in order to allow for automatic testing
- doc comment should just be free form text
-
RFC 64 justifies tying it to markdown
- specify scope for which doc comments apply, and provide rationale for decision
- maybe only for bindings
- functions can also be written without a name just top-level in a file though
- the RFC should be limited to the free form doc comment, and leave the rest for future work
Action Items
-
@spacekookie: Tutorials and explanation for module system
-
@infinisil: Reference docs for module system
-
@hsjobeki: Capture discussion outcomes in RFC alternatives and arguments
1 Like
Hosted by Flying Circus.