Comment by BoppreH
10 hours ago
> How far back in the stack do you go?
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.
Why stop at `git clone`? Why not include `apt install git` and equivalents for all OSs?
Whenever I write documentation, my first step is to explain how silicon can be used as a transistor.
Yeah well I produce home grown silicon in super novae.
'If you wish to make an apple pie from scratch, you must first invent the universe.'
I used to think it was a struggle to walk the user through introductory EM physics.
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.
In my company that comes be default. Also, `git clone` helpfully includes a canonical path to the repository, in case you found the README laying around somewhere.
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.
If Windows/MacOS doesn't ship git by default, then yes, that should be included. On Linux, the people who are running Linux From Scratch can probably infer what the problem is.
I don't know about these days, but at some point neither Debian or Ubuntu Server shipped with Git. You can still find tutorials that start with apt-get update and apt-get install git-core