My/Pref/Writing/Avoid Distractors such as Awkward or Superfluous Metaphors

• Metaphors are the relish of communication: a delicious, beautiful hot-dog topping for the occasional meal — not a daily, general-purpose condiment or ingredient.
• By "metaphor" in this page I'm referring to figurative comparison of any kind a true Metaphor, a Simile, an Analogy, or any other comparison.
• There are more ways to inappropriately use metaphors than to appropriately use them. They are best avoided unless the situation is worth the extra effort. Any metaphor that becomes a Distractor is a smile a toothless mouth. Know what I mean? You don't? Well, there you go, now you understand what it feels like to be distracted by a useless comparison (sorry to do that to you! let's do that less).
• Keep metaphors special by only using them in places where you need to command the reader's attention in a special way. For example, if there's a crucial aspect of the design of a system that could go very wrong, and you need to talk about trade-offs between alternatives, maybe then it's appropriate to use a metaphor to heighten draw the reader's attention to how special that moment is.
• For example, don't refer to the "teeth of the spec," instead, refer to "how to check if something meets the specification," which is clearer and plainer (My/Pref/Writing/Use Plain language).
• Often times, this intersects with My/Pref/Writing/Avoid Jargon, Especially Tech-speek; don't say that you "fork" something if what you mean is that you're going to make a copy of something or say "that's the real fork" to refer to a decision we need to make.
• When using metaphors, be careful with word choice and proximity to topics. Don't mix metaphors in the same paragraph.
  • Examples to avoid
    • Five clashing metaphors in a single sentence:

      • Your sketch is ambiguous on one hinge, and it's the same illegal-state knot from before wearing new clothes.
        

      • The images collide — sketching, a door hinge, a knot, and clothing, on top of the "illegal state" figure — so the reader decodes pictures instead of the point. Plainly: the description is unclear on one point, and it repeats an ambiguity from earlier.