The best way to determine whether a detail should be included is to extrapolate from your experience teaching people in real life. I have literally, in my entire life, never observed a person ruining chocolate chip cookies by using too high or too low a cocoa content. I don’t even think about cocoa content when making chocolate chip cookies. From this experience I conclude it is not necessary to specify cocoa content. If you think cocoa content is something a reader is likely to get wrong in an important way then you should specify cocoa content.
You should always include all the details necessary for the reader who knows x to perform y competently. What I mean by “[y]ou are not allowed to overgeneralize” is that you should never say anything technically incorrect. Never communicate information that will have to be corrected later.
People who have trouble getting to the point often benefit from a wordcount limit. If you are a rambler then you should enforce a wordcount limit on yourself.
I looked up lots of details when writing my Vim guide. I don’t think requiring details to be remembered off the top of your head without googling is a good rule when writing a guide. On the other hand you should not use quotes unless you can recall the gist of them from memory. (But you should google them anyway to get the words exactly right.)
“No numbers” is a bad rule when writing a guide. Precise language is good. Numbers are the most precise language. Numbers are good. Err on the side of being too specific when writing a guide.
Removed.
The best way to determine whether a detail should be included is to extrapolate from your experience teaching people in real life. I have literally, in my entire life, never observed a person ruining chocolate chip cookies by using too high or too low a cocoa content. I don’t even think about cocoa content when making chocolate chip cookies. From this experience I conclude it is not necessary to specify cocoa content. If you think cocoa content is something a reader is likely to get wrong in an important way then you should specify cocoa content.
You should always include all the details necessary for the reader who knows x to perform y competently. What I mean by “[y]ou are not allowed to overgeneralize” is that you should never say anything technically incorrect. Never communicate information that will have to be corrected later.
People who have trouble getting to the point often benefit from a wordcount limit. If you are a rambler then you should enforce a wordcount limit on yourself.
I looked up lots of details when writing my Vim guide. I don’t think requiring details to be remembered off the top of your head without googling is a good rule when writing a guide. On the other hand you should not use quotes unless you can recall the gist of them from memory. (But you should google them anyway to get the words exactly right.)
“No numbers” is a bad rule when writing a guide. Precise language is good. Numbers are the most precise language. Numbers are good. Err on the side of being too specific when writing a guide.