Notes
- Due to personal reasons @maj has to step down as an editorial lead
-
@zmitchell: How to do these meetings going forward?
- From @maj’s report
- Typically brain vomit ↔ edit cycle
- But we’ve been editing things more in-place, perfecting them while doing so
- Rather than work on a single tutorial at a time, rather come up with a skeleton of skeletons:
- Which tutorials should exist first, delegate it to individuals working asynchronously to come up with as skeleton for the tutorial and give feedback
- Monthly cadence, proposal:
- First week: Here’s the tutorials we want skeletons for for the next month
- Second week: Post on Discourse for what tutorials we could work on, seeking feedback from individuals that know about these topics
- Rest of the weeks: Asynchronous work creating the skeletons, in the meetings review questions that come up and finalize skeletons
-
@henrik-ch: Great idea. Would love to see the report too.
- Would also like to be able to come to @zmitchell for help
-
@zmitchell: Single points of failure like that aren’t great. Better is tagging me when I could help with a PR/issue
-
@infinisil: Good proposal, even if not perfect, we can refine it, better than unstructured.
-
@zmitchell: Good to get @roberth to do it. Would like the skeletons for the rest of the month. A bit like a month-long sprint.
- We might get started on a tutorial but hit a snag, at which point we could reach out to @roberth in some convenient way
- Not sure how to work on this, can’t review issues, don’t want to create a PR for every skeleton.
- Could use hedgedoc, not persistent though, not ideal
-
@henrik-ch: skeleton branch on nix.dev
-
@khaled: Draft PR’s?
-
@roberth: Wiki? Separate repo?
-
@infinisil: Separate repo idea++, doesn’t have to be persistent
-
@zmitchell: Output needs to be discussed. Missing parts in skeletons might be confusing even if they are intentionally missing, good to see the discussion history
- Why not use a separate directory in the nix.dev repo?
-
@henrik-ch: Also better for newbies to find it.
-
@henrik-ch: Could work on master branch and pollute the history, but we could put it on a separate branch to not do that.
-
@zmitchell: Merging of PR’s will be a single squashed commit, so the branch history can be messy
-
@henrik-ch: documentation survey also works similarly, with a dedicated non-master branch committed to, works quite well
-
@infinisil: Same repo and PR’s sounds good, could even have the skeleton at the right place already, but not render it yet
-
@zmitchell: Can even mark it as a draft in some static site generators too
-
@zmitchell: Regarding week 2 of the above proposed plan, discourse post or so for feedback
- We want these tutorials covering these things
- What then? Just let people discuss?
- Should have specific questions for people to answer
- As a beginner, hard to form questions without knowing the content already that well
-
@roberth: Following Diataxis, e.g. for a derivation you’d ask for an explanation or a reference, not a how-to or a guide. Should focus on activities
-
@zmitchell: E.g. how
mkDerivation makes things easier than runCommand
-
@khaled: Step back further, why do we do this, what do we want to gain? We don’t need to show to build a rust package
-
@roberth: Confusing tutorials and how-to’s.
runCommand is not necessary to build rust programs. Explaining runCommand sounds like something more for explanation-style docs
-
@infinisil: I came up with mentioning
runCommand, I think it’s useful to teach to people, lead to mkDerivation, builders later
-
@zmitchell: Feedback taken: Focus on tutorials, not other material
-
@zmitchell: What activities can we do to cover specific concepts. Or rather: What things do we want people be able to do.
-
@khaled: State activities like “How to package a program”?
-
@zmitchell: Too broad, but also packaging a specific language/framework is a bit too detailed, we shouldn’t cover all of those
-
@zmitchell: Maybe how to package a program in different scenarios instead. Sometimes it might be easy to package something, could even just run some commands with
runCommand or mkDerivation. Focusing on scenarios of what could happen
-
@roberth: It’s okay to replicate stuff in the Nixpkgs manual, which should be reference docs, anything more tutorial/guide-like should be incorporated and replaced with a reference. Some of those would be very simple, even for specific languages. Some of those might be harder where the reference doesn’t fully cover it.
-
@zmitchell: Keeping it a tutorial and not a how-to or explanation might be difficult. Guide-to shouldn’t include prose.
-
@zmitchell: If the tutorials are written by various people and we want the same standard, we need better contribution guidelines
- Could create a tutorial template with frontmatter, headers, etc.
- Guidelines for voicing, how to write it
- Action item could be to come up with a tutorial-specific contribution guideline
-
@infinisil: Fixing these issues as they come up sounds easier to me
-
@zmitchell: Fine line, if it’s not written down it’s going to cause more work, baseline guidelines would be good
-
@infinisil: Could link to a master tutorial with a desired style
-
@roberth: A good example is good but guidelines are important, should also pay more attention to Diataxis, tutorials vs guides?
-
@zmitchell: Tutorials are about muscle memory. If you’re an air-like pilot trying to land a plan, how-to’s is the checklist of what to do, tutorials are about getting the muscle memory down to what can happen what to do in which cases.
-
@infinisil: Tutorials are about teaching how to handle things you haven’t seen yet
-
@zmitchell: Alternate name for how-to’s is cookbooks, just tell me how to do something
-
@zmitchell: Conclusion: Contribution guide good, example good
-
@zmitchell: Next week start planning which tutorials we want to work on for next month. Should we revisit the tutorials already created to make sure they’re tutorials?
-
@infinisil: I think we did create tutorials, but could check it briefly too
-
@zmitchell: @roberth: Please go over the things already created, give feedback on whether it’s a tutorial and a good activity for somebody to do, or if there’s something better
-
@roberth: Need to get permission to nix.dev
-
@infinisil: Could get everybody in the Nixpkgs maintainers team read-only access, like Nixpkgs
Action items
2 Likes
Hosted by Flying Circus.