Should vs. Does, again.

MySQL documentation states that replicating from a 5.0 master to a 5.1 slave should work. This is very different from stating that it does work. That section of the manual should enter the 5.1 no-use case competition.

Frankly, I hate the word “should.” To see it in vendor documentation like this is terrible, because it’s a weasel word. It puts the onus of testing and support on the end user, and gives the vendor a cop-out when it doesn’t work. “Well, we only said it should work, not that it does.” Not saying that MySQL does that, but other vendors certainly do.

For me, seeing “should” in this situation always translates to “does not” when I start thinking about the reasons for the hedging. Have they not tested it? Maybe they have tested it but it fails sometimes and they haven’t figured out quite why. Maybe they want to say it “does” work, but they just need to qualify it with more criteria they haven’t documented yet.

Regardless of the reasons, and for most people who need to rely on features like this for production systems, having “should work” in your documentation is functionally identical to not having the feature at all.

4 thoughts on “Should vs. Does, again.”

  1. Agreed – in documentation, “should” is not ok.

    However, for those of us that write reports with recommendations, “should” shows up left and right. For example, “Cisco ASA patching should be a high priority for the Acme organization.” You don’t get to tell them what to do – they have to think you’re making a suggestion and they’re making the decision.

  2. I’m with Matt on this. I was ok with “should” depending on the situation. In documentation, it has to be one or the other.

  3. @Ben:

    Yeah, recommendations are fine. What I rail against is documentation & reports that need to be concrete, yet have words in them that indicate something has been left untested. Words like “should” & “might.”

Comments are closed.