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.
@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
@fricklerhandwerk: True. Explanation is also desparately needed though.
@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
@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
conclusion/solution should be obvious for all readers based on that
input from this discussion should be included in a condensed manner