

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.



At times that shit is pretty much the opposite of what should be done.
Fail Fast is generally a much better way to handle certain risks, especially those around parts of the code which have certain expectations and the code upstream calling it (or even other systems sending it data) gets changed and breaks those expectations: it’s much better to just get “BAAM, error + stack trace” the first time you run the code with those upstream changes than have stuff silently fail to work properly and you only find out about it when the database in Production starts getting junk stored in certain fields or some other high impact problem.
You don’t want to silently suppress error reporting unless the errors are expected and properly dealt with as part of the process (say, network errors), you want to actually have the code validate early certain things coming in from the outside (be it other code or, even more importantly, other systems) for meeting certain expectations (say, check that a list of things which should never be empty is in fact not empty) and immediatly complain about it.
I’ve lost count how many times following this strategy has saved me from a small stupid bug (sometimes not even in my system) snowballing into something much worse because of the code silently ignoring that something is not as it’s supposed to be.