@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: 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