- Team details
- Past meeting notes
- Attendees: @fricklerhandwerk @infinisil @olaf @jeremiahs @evils @zmitchell @khaled @henrik-ch @riceicetea @ethan:roo.ke (Matrix) @pennae @StefanSchroeder
- Notes by: @infinisil
Agenda
-
@olaf GSoD structure (20-30 min)
- Google Season of Docs 2023 Project Proposal - HedgeDoc
- determine scope and assign who will work on the outline
- determine what to do with the budget specifically
- @zmitchell on learning journey working group
Notes
Google Season of Docs
- Discussed proposal on Tuesday, @fricklerhandwerk made a PR to refine it
-
@olaf: Changes:
- Converted to Google’s suggested document structure
- Still not very clear about where to put budgeting though
- Title: “Learning journey” (suggested by @fricklerhandwerk) or “Get the basics right”
- Some minor sentence changes
- Rewrite to focus on reference docs, keeping learning journey around.
- Also keep guides/tutorials around, but not sure how it fits into the outline.
- Mentions how we benefit from the improved references
- Mention what is out-of-scope
- More success measures, though I don’t think there’s a good way to do it
- E.g. measuring success by tutorial length
- @fricklerhandwerk: The most important one should be successful onboardings
- How and which mentors should be be mentioned?
- Who’s actually applying?
- @fricklerhandwerk: Formally the NixOS foundation. Documentation team is executing it, foundation will approve it.
- @olaf: Should write from the perspective of the NixOS Foundation
- Converted to Google’s suggested document structure
- (quick feedback from the group)
-
@fricklerhandwerk: What is the scope that we should cover? Which references and tutorials specifically?
- We’re limiting ourselves to “declarative environments” as a starting point
- Allows being more concrete and specific about how to allocate the resources
- (): Write your own package; this is something that happens quickly
-
@fricklerhandwerk: Might be too far into the curriculum, possibly too much work, but would be great if we get that far
- Maybe we should set the final scope while we’re at it, since it’s easier to tell when we know who will participate
-
@fricklerhandwerk: Might be too far into the curriculum, possibly too much work, but would be great if we get that far
-
@StefanSchroeder: Suspicion: There’s more questions about administrative tasks, less about building packages
- @fricklerhandwerk: System administration is an advanced use-case from our perspective, let’s switch the order around to focus on more beginner things first
- @zmitchell: Only metric of success being more user testing is not great. Doesn’t say what goals we want, e.g. faster time to learn X.
-
@zmitchell: IMO it’s a hard sell without more concrete outcomes
-
@pennae: Could take the number of repeated beginner questions
-
@fricklerhandwerk: Sounds good to me, can ask question askers in the community for that. Anectodal is good enough for now
- @Jeremiahs will ask around and get some data for next week
- @Jeremiahs: Good metric: Time for someone to build their own package
-
@fricklerhandwerk: Sounds good to me, can ask question askers in the community for that. Anectodal is good enough for now
-
@pennae: Could take the number of repeated beginner questions
-
@khaled: Can we list out previous tasks and how long they took and what confusions there were?
- @fricklerhandwerk: The user studies do that
- @khaled: Let’s point those out and aim to eliminate those specific problems
- @khaled: Let’s focus on specific tasks we’d like to get done
-
@fricklerhandwerk: Have a scenario of somebody in a company starting out with Nix, up to patching existing packages
- something like that could be used as a standardised test of proficiency
- @StefanSchroeder: E.g. if you go through a certification somebody would look at the steps you’re doing and the workflows [?]
-
@fricklerhandwerk: Second task: Outline to contribution guide
- expanding on the use-cases, activities, what do you need to do to roll your own package, update a package, etc.
- Who wants to break down the skills required for that?
- @Jeremiahs and @olaf will help with that and make a draft for next week
- @olaf: Focus on listing tutorials that convince google (@fricklerhandwerk: ourselves first!)
- We’re limiting ourselves to “declarative environments” as a starting point
-
@fricklerhandwerk: About money, what’s the best use?
- We shouldn’t give money to people that have a well-paid full time job, won’t magically create more time for them.
- Different roals
- Research, learn, write down in bulk
- Nix expert
- Didactics expert(s)
- Editor
-
@evils: Shouldn’t hesitate to have somebody be paid for this, if we can’t find a volunteer
-
@fricklerhandwerk: yes, most of the money should go to the experts to guide the effort and share knowledge
- The rest for enthusiasts, students (possibly from developing countries where the money really matters), mentors from the community who want to chip in
- would use the opportunity to learn the tech and skills on the fly
- The rest for enthusiasts, students (possibly from developing countries where the money really matters), mentors from the community who want to chip in
-
@fricklerhandwerk: yes, most of the money should go to the experts to guide the effort and share knowledge
- Probably can’t get volunteers to do all of that, get paid people to help volunteers
-
@fricklerhandwerk: Volunteers can pick specific tutorials, focus on those, research, write, consult with experts
- that will take the bulk of the time
- imagine undergrad in some technical field
-
@olaf: Should technical support also be covered by volunteers? @fricklerhandwerk agrees
- @fricklerhandwerk: maybe something for @yuki_is_bored?
-
@fricklerhandwerk: Hopefully we can get volunteers just doing it for the experience. Can think of it as a course Google pays the TA’s for.
- @zmitchell volunteers for the didactic support, has a strong background
-
@olaf: 6 volunteers seems reasonable, 3 experts (writing expert, didactics, nix expert)
- @fricklerhandwerk: Aim for $5000 per expert, will probably adjust this to GDP matching GSoC rules
Learning journey working group
-
Let’s inform the people in the meeting here
-
@zmitchell: Priority: How to best teach Nix
-
Short-term goals:
- For example: Language guides
- e.g. for Rust, there are different ways to do it, which one to pick
- Establish documentation structure, so they know where to put stuff when they want to contribute.
- This is hard to know currently, but really important to get people going quickly
- Identify gaps in existing docs and website structure
- For example: Language guides
-
Long term: Reorganize body of existing docs
-
Is @infinisil part of it?
- @infinisil: Okay for the occasional review
-
@olaf: Discourse is very helpful when you have a line that you don’t understand when writing a tutorial, good way to learn things
-
@fricklerhandwerk: Should update documentation resources survey for what exists out there
- look at discourse Guides and Links categories
- Move the existing survey to nix.dev as an easy task
-
@zmitchell: Working group timeline:
- Get the PR merged
- Establish working group
- Decide on structure where to put things
- Do survey of existing docs
-
@zmitchell: Initially bi-weekly meetings was the goal. Only have weekly meetings at the start to get off until we’re in a steady state and not as many things to discuss anymore
-
@StefanSchroeder: Another goal: Useful documentation is often outdated, what is the process to archive old documentation, what are the requirements for the docs
- @Jeremiahs: Solution: Docs is tied to the version. Check a box for a tutorial when it still applies to the new version
- @StefanSchroeder: Need to review every chapter for if it’s still valid
- @zmitchell: Problem: There’s multiple repositories
- @zmitchell: Prerequisites sound reasonable. Also display “updated at” timestamp
- @StefanSchroeder: Allow users to confirm that a tutorial still works with specific versions
- @khaled: Make it testable, run in CI
- @fricklerhandwerk: All that can be done, task for the “technical task-force” (which doesn’t exist yet)
- @pennae: and would be easy enough to extend to spit out a compendium of all examples/code blocks