alt Hacker NewsIt's a tricky problem. How far back in the stack do you go? The README assumes that you know how to use git to check out the files - or that you can easily save them from the repository. Should it include that as a step in the tutorial?
As I say in the linked article, it depends on what sort of user you have. For a "getting started with Raspberry Pi" document, you might well want to include how to insert an SD card etc.
I'll have a think about the best way to help people figure out if they're running PHP. Thanks for the feedback!
Replies
Installation instructions usually (should) have a “prerequisites” section. You don’t have to explain how to install the prerequisites, but they should be listed.
> 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.
Generally it seems like good READMEs assume you have a compatible OS ready to go, but will give you a summary of all commands to get a working setup from there.
It can't hurt to make a sentence or two about assumptions.
Like "This manual assumes that you have a Linux/BSD, a C compiler, GNU Make, and a text editor".
It's really not that tricky at all, every install document I ever wrote has a "prerequisites" section telling you the prerequisites.
Feedback and issues you need to troubleshoot with your projects is a good indicator of your audience level, and from my experience it’s helpful to understand that documentation is always under development just like the code
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