Attendees: Kevin @xin(discourse) @iron-shark(matrix), @olaf, Philipp, @fricklerhandwerk, @pennae, @zmitchell, @infinisil, Gabriella Gonzalez, @henrik-ch, @wiseh
Notes: @infinisil
- @fricklerhandwerk welcomes everyone and opens the meeting - sharing agenda
- Let’s do introductions!
- Who’s in the team?
-
@fricklerhandwerk: For now let’s just connect and get the hang of it
- will determine a conrete roadmap and once people attach to tasks we’ll formalise
- @infinisil: So let’s make it official only later
-
@zmitchell: How to decide? Vote?
- @fricklerhandwerk: so far was not relevant in practice, but have to address this as a fallback, please open an issue on nix.dev
-
@fricklerhandwerk: For now let’s just connect and get the hang of it
- Looking at 2022-10-22 Documentation team meeting notes #12 - NixCon edition
-
@fricklerhandwerk: Problem with porting from manual to nix.dev due to license mismatch
- have to consider that in the future
- @Gabriella: What if we endorsed a license for docs, so other people can use it and we can port the docs around
- @fricklerhandwerk: Everyone, please liberally open issues in nix.dev, doesn’t look official, but you can treat it as such
-
@olaf: Not all docs need to use the term “derivation”, let the problem be dealt with by the author of a section that can’t avoid it
- @fricklerhandwerk: derivations are often in the foreground due to how the ecosystem grew and still happens to work
-
@Gabriella: E.g.
.drvfiles need to be understood by tooling. People just installing things don’t need to know what that is
- @olaf: Let’s try to get as far as possible without getting side-tracked
-
@Kevin: Who’s the target audience for the docs?
- @zmitchell: Should be able to support everyone, see also my blog post on a possible vision
-
@fricklerhandwerk: Yes, have to be able to both teach from first principles ,from the ground up, and people more inclined to that learning style can bring the ecosystem forward. But also have to support users who just want to get the job done. We have only very limited resources for a big task, so have to figure out what to do first.
- So far there was consensus to treat developers as the most important target audience, they can usually help themselves
-
@Gabriella: Even that might be too broad of a target audience. E.g. NixOS as a desktop is already too broad of a focus
- @fricklerhandwerk: How to narrow down the audience more?
- @Gabriella: Picked NixOS for their book because it provides a lot of value, wherease Nixpkgs has a lot of pitfalls.
-
@Kevin: Makes me sad as a NixOS user and programming beginner, but it makes sense, gotta start somewhere
- @fricklerhandwerk: Nix is increasingly a first programming language. It’s messy but a nice language to learn about programming, since it doesn’t have a lot of moving parts (though a lot of accidental complexity and quirks)
-
@Kevin: Something else: why isn’t home-manager part of Nix? “Documented” in GitHub comments, not docs
- Will publish first chapters of my own learning journal soon
- @fricklerhandwerk: Even NixOS is an extended use-case, requires a lot of buy-in
- @olaf: Want to mention that @fricklerhandwerk has a particular view on this. Contributors can work on what they think is most important for them
- @fricklerhandwerk: We can provide a main entry-point for people to see Nix as, and ignore other ways for now. We can (and should) shape the journey of how people see Nix for in order to provide a better experience
- @zmitchell: Back to Summer of Docs, should we vote on something specific?
-
@fricklerhandwerk: Flakes?
- @infinisil: Probably not our place to decide to work on docs, needs to be stabilized first
- @fricklerhandwerk: Learning journey
- @fricklerhandwerk: Evaluate user studies
-
@zmitchell: Two aspects: (Improving or creating new docs) and (where to put documentation).
- Where should we guide people to put docs?
- @fricklerhandwerk: Need to work together to establish the vision
-
@henrik-ch: Let’s have a task force for the Summer of Docs
- @fricklerhandwerk: Sounds good to me
-
@olaf: What does the application look like? Should it be both infrastructure and content?
- @infinisil: Depends on what people want to work on
-
@fricklerhandwerk: AFAIK the NixOS Foundation would apply with one project, if approved we could ask the NixOS Foundation for additional funds
- writers can apply directly with the foundation to get (part of) an approved grant
-
@infinisil: When’s the deadline?
- March 24 2023
-
@fricklerhandwerk: Problem with porting from manual to nix.dev due to license mismatch
- Let’s schedule a work meeting for next week, make sure to fill in your availability
-
@fricklerhandwerk: Let’s look at the project board next time, look at more concrete tasks
- Get some experience with particular issues
- Start establishing a vision and roadmap
- Finding the right place for things should be the primary goal in the next ~3 months, we should do actual work between the meetings
- @infinisil: Also breaking down manageable tasks for people to just pick up, and a clear guideline how to go about them
Agenda
- introductions (10 min)
- agree on time for working session (5 min)
- brainstorm project ideas for Google Season of Docs (20 min) (expanded to rest of session)
-
triage and assign issues on the project board (10 min)postponed to next time
Project ideas for Google Season of Docs
Guidelines: Project ideas | Google Season of Docs | Google for Developers
Prior art: 2022-10-22 Documentation team meeting notes #12 - NixCon edition
- dealing with secrets
- write and generate docs for all the Nixpkgs functions, builders etc. (cf. Hoogle/Noogle)
- what’s a derivation anyway?
- stdenv
- nixos.org rewrite
- language frameworks
- structuring NixOS Wiki
- flakes?
- possibly in form of a factual account of history and current state of affairs
- learning journey
- evaluate user studies
- restructuring documentation architecture
- survey of third-party documentation
- versioned manuals