Often these issues come down to two sides digging in their heels: "just don't make mistakes" vs "just make it foolproof". Somehow accidents continue to happen.

Often these issues come down to two sides digging in their heels: "just don't make mistakes" vs "just make it foolproof". Somehow accidents continue to happen. What I have noticed with manuals is that I usually approach them in one of three different modes: * what is this / how does it work / is it what I need? * which flag or option that does _? * what does this flag or option do? The first requires a bit more introduction and tutorial than a typical manual will provide because they're usually written by someone who is so familiar with what it does that they can't remember life before understanding it. There is either too little explanation or too much detail, eg arcane ISO standards and niche uses like "week number". Most likely you need examples for it to finally sink in. The second is probably the most frequent use of a manual, when you're still testing things out. You know the behavior you want and are scanning through the descriptions to find the right match. It's like reading a dictionary by value to find the right key. This is where the infamous "which tar options do I want?" meme comes from. The third is what most manuals are optimized for. It's a reference for quickly looking up someone else's code to figure out what it does. Each of these uses requires a different format. In the first case you need a lot more text and instruction that would be unnecessary noise for the other two situations. In the second case you want things organized by function, and preferably with context about the most commonly used options. The third is where alphabetical order makes sense.