Stay organized with collections
Save and categorize content based on your preferences.
In documentation, don't make excessive claims. An excessive claim is an assertion
in the documentation that does any of the following:
Makes a statement about performance or cost that isn't easily verifiable with data
that's available to the reader.
Makes a statement about security that would be invalidated by a security incident.
Makes a statement that might be interpreted as subjective or even disparaging,
especially about third-party products.
When you're assessing whether some text makes an excessive claim, take into account
not just what's true today about a product's performance, cost, security, or
functionality, but what might be true in the future.
Consider the following guidelines:
When you describe products, avoid superlatives like best, simplest,
fastest, never, and always. Similarly, be
careful about words like ensure and guarantee and use them only when
something can truly be ensured or guaranteed.
If you make specific performance claims—how fast a product is, how much storage
it requires, and so on—make sure that you reference the source of your information.
If documentation claims that a product is secure, the documentation
is invalid (and not credible) if someone succeeds in compromising the product.
It's safer to suggest that a feature "helps with security" or "is designed for
security" because those statements are true even if a security incident occurs.
A statement that you make about a competitive product might be untrue if you
misinterpret how the product works, or later if the other company comes out with
a new release.
The safest approach is always to write factually and objectively, limiting what you say to
verifiable information that will be true over the lifespan of your documentation.
Recommended: Our product
distributes datasets and computation in memory across a cluster, and
therefore it can be faster for this scenario than ExampleCorporation's product. For
more information, see Performance comparison.
Not recommended: Our product is
faster than ExampleCorp's product.
Recommended: Using our security product
is part of an overall strategy that helps prevent account takeovers from phishing attacks.
Not recommended: Our security product
prevents account takeovers from phishing attacks.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-10-15 UTC."],[[["\u003cp\u003eAvoid excessive claims in documentation, which are statements about performance, cost, or security that aren't easily verifiable or could be invalidated by future events.\u003c/p\u003e\n"],["\u003cp\u003eRefrain from using superlatives and subjective language when describing products and features, instead focusing on factual and objective information.\u003c/p\u003e\n"],["\u003cp\u003eWhen making specific performance or security claims, ensure they are backed by verifiable data and consider potential future scenarios that could impact their validity.\u003c/p\u003e\n"],["\u003cp\u003eEmphasize the intended benefits and design of features rather than making absolute guarantees, especially regarding security.\u003c/p\u003e\n"],["\u003cp\u003ePrioritize writing factually and objectively, providing verifiable information that will remain true throughout the documentation's lifespan, even when comparing products.\u003c/p\u003e\n"]]],["Documentation should avoid excessive claims about performance, cost, or security that are unverifiable or could be invalidated. Avoid superlatives and words like \"ensure\" or \"guarantee\" unless they are absolutely factual. If performance claims are made, cite the information source. Instead of claiming a product is secure, state it \"helps with security.\" Focus on objective, verifiable information that remains true over time, avoiding statements that might be subjective or disparaging to third-party products.\n"],null,[]]
