from experience in ENT support where i was sending instructions & quick fix scripts to technically capable persons, you will learn very fast when you’ve missed the mark with your documentation / instructions. tons of times i had ready made solutions that i thought “just copy and paste and go what could possibly go wrong?” and was caught off guard how often a little too much knowledge lends to confusion. i am not blaming the users here it is my fault that i didn’t explain things like “no don’t change this date in the fix that is a special date when the issue could have earliest occurred and it’s there to avoid grabbing more than we need to parse”, but i didn’t tell that so of course people changed it to all sorts of dates thinking they had to
such feedback and issues also got me way better about writing code that avoided chances for such mistakes as i didn’t want users to have to read a novel to understand what to do; it’s a fine balance between what to solve with documentation and what to solve with code
Tells something about the project, IMO.
My rule of thumb for my READMEs: there should be a list of commands, that when executed in order and in a clean machine, result in the software doing something useful. Yes, this includes `git clone`.
If there's something the user might already have, like the webserver, I add a comment "skip this if you already have a web server". If there are any shortcuts that make it not production-ready, it's time to break out the ALL CAPS.
Limiting the operations to simple commands also helps me keep honest about the instructions (no hidden assumptions), and forces the software to be minimally testable.
'If you wish to make an apple pie from scratch, you must first invent the universe.'
But, it turns out that was a walk in the park compared to explaining how to acquire and isolate the dopants, not to mention building up the pure silicon wafers.
Otherwise, yes, I would include apt install for the dependencies, which is also incredibly valuable to make explicit. The only tricky part is what package manager to reference.
Like "This manual assumes that you have a Linux/BSD, a C compiler, GNU Make, and a text editor".