claim-001 should GuidesAPI docsMarketingBlog Do not attribute human qualities to software or hardware (anthropomorphism).
Claims and accuracy
This page covers how to describe what software does without overstating it: no human qualities attributed to code, and no claims you can’t back up. Time-sensitive wording is covered on the time-based content page.
Don’t anthropomorphize software
Section titled “Don’t anthropomorphize software”Examples
- ✓ The service rejects requests that carry an expired token.
- ✗ The service sees that the token is expired and decides to reject the request.
Rationale
Attributing human qualities to software is imprecise and can mislead about what it actually does.
Avoid unverifiable claims
Section titled “Avoid unverifiable claims”claim-002 should GuidesAPI docsMarketingBlog Avoid excessive or unverifiable claims: superlatives, absolute performance or security guarantees, grandiose framing of significance, and potentially disparaging statements about third-party products.
Examples
- ✓ The gateway is designed to remain available during a zone failure.
- ✗ The fastest, most secure gateway on the market, far more reliable than legacy alternatives.
- ✗ This release marks a pivotal moment in the evolution of the platform.
Rationale
Superlatives and absolute guarantees are hard to substantiate and undercut trust, and disparaging a third party invites dispute.
Name any authority you cite
Section titled “Name any authority you cite”claim-003 should GuidesAPI docsMarketingBlog If you attribute a claim to an authority, name it: a specification, a benchmark, a named study or team. Don’t attribute it to an unnamed one, such as experts agree, it is widely considered best practice, studies show, or observers note. A claim you make yourself needs no attribution; state it and state why.
Examples
- ✓ RFC 7234 requires caches to honor the
no-storedirective. - ✗ It is widely accepted that caches must honor the
no-storedirective. - ✓ Retry with backoff; in our load tests, immediate retries doubled the error rate.
- ✗ Industry experts agree that retries should use backoff.
Rationale
An unnamed authority hides the absence of a source. A reader can check a named specification or benchmark, but not “experts.” Naming the source also keeps the sentence in active voice with a real subject.