I Prefer a playbook to a recipe card. The playbook should spell out the goal and the 'why's of the steps. Because if the process throws an error due to upgraded code etc, then you can be stuck at step one with no path forward. With some playbook annotation you at least know expected out come and why you are running a command etc.

When I have gone to docker hub I always view multiple images and see what their writeup is like. Some just assume you 100% know all dockers subtleties, some have a one liner, but there will be a helpfull soul who spells out what steps to do, and what the best options to set etc. Like a mini tutorial.

I find the mini tutorial to be widely beneficial, because it removes the blackbox nature, and gives new onboarding users a chance to grasp the concepts docker works with.

It's like the difference between going to a mechanic that has you sit by the coffee machine in the office while they change your brakes and they come back and say "I swapped the new pads in", vs them pulling up a chair in the shop and explaining the process "here I'm wirebrushing the back of the wheel and the hub, to make sure when it goes back on there is no corrosion debris stopping a parallel fit..now I'm applying high temp grease so that the hub and wheel don't sieze together from corrosion and make next removal easy"

The info is probably useless to a seasoned mechanic that had a broken hand so had somebody else do their brake work, but highly useful to the next gen of person that can absorb it and know whats and whys.

[–] SmartmanApps@programming.dev 2 points 5 days ago

It’s like the difference between going to a mechanic that has you sit by the coffee machine in the office ...

Good example. I just wanted to add that the place I go to for tyres, if there's some kind of issue (like with balance or alignment), sometimes they even take me into the workshop (where customers are usually not allowed) to show me what the issue is.

[–] Aceticon@lemmy.dbzer0.com 2 points 6 days ago (1 children)

Yeah, that's much better.

Personally I detest not understanding what's going on when following a guide to do something, so I really dislike recipe style.

That said, I mentioned recipes because recipes meant to be blindly followed are the style of guide which has the lowest possible "required expertise level" of all.

I supposed a playbook properly done (i.e. a dumbed down set by step "do this" guide but with side annotations which are clearly optional reading, explaining what's going on for those who have the higher expertise levels needed to understand them) can have as low a "required expertise level" as just a plain recipe whilst being a much nicer option because people who know a bit more can get more from it that they could from just a dumbed down recipe.

That said, it has to be structured so that it's really clear that those "explanation bits" are optional reading for the curious which have the knowhow to understand them, otherwise it risks scaring less skilled people who would actually be able to successfully do the taks by blindly following the step-by-step recipe part of it.

[–] BCsven@lemmy.ca 3 points 6 days ago

That said, it has to be structured so that it's really clear that those "explanation bits" are optional reading for the curious which have the knowhow to understand them

Yep, totally. This past year I spent a lot of time setting up an LMS with content.
I included sections that were tips, good to know, for awareness, etc.

Maybe only 1 out of every 20 users might expand the section, but if they do then there is a clear explanation of why this particular thing functions this way and how to make it work in alternate usecases. Images and explanation, before and after, etc.