Comment by zahlman
2 years ago
Eh, I've found that doc pages that try to establish really hard lines will still fail, and end up at a high level of quality. I think of it like a programming principle in the "don't mutate global variables" or "write shorter functions" category: you don't have to get it completely right, but most people really would be better off moving more in that direction rather than away from it.
The approach works better with dedicated technical writers. It makes sense to have distinct user-focused goals for documents before they’re written, and then just dig into the necessary parts of the software enough to make that happen as needed. When it’s developers doing the docs, they’re approaching it from the other end. They’ve got a chunk of code they need to cover, and reasoning about user needs is pretty difficult from that vantage point. Picking an approach vector when you don’t know the airport.
I think that's a SHOULD in the send of RFC 2119: "There may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course."
Treating a SHOULD as a MUST even when particular circumstances are against it, is one way to fail at a task.
It's like Orwell's last rule, where many people seem to miss that it's the punchline of the whole essay: "Break any of these rules sooner than say anything outright barbarous."