# Claims and recommendations

From the Google developer documentation style guide; each section names its
source page. Two sections are extensions and are marked as such: the second
half of "Outcomes", and "Verified versus assumed".

Guide content © Google, used under CC BY 4.0
(https://creativecommons.org/licenses/by/4.0/).

## Contents

- [Excessive claims](#excessive-claims)
- [Recommendations: must, should, can](#recommendations-must-should-can)
- [Outcomes](#outcomes)
- [Future features](#future-features)
- [Timeless wording](#timeless-wording)
- [Third-party products](#third-party-products)
- [Third-party content](#third-party-content)
- [Verified versus assumed](#verified-versus-assumed)

## Excessive claims

Source: https://developers.google.com/style/excessive-claims

An excessive claim is an assertion that does any of the following:

1. States something about performance or cost that the reader can't verify with
   data available to them.
2. States something about security that a single incident would falsify.
3. Reads as subjective or disparaging, especially about a third-party product.

Avoid the superlatives *best*, *simplest*, and *fastest*. Avoid *never* and
*always* in claims about behavior, as in "never fails" or "always available".
Both are fine as instructions ("never commit a credential"). Take care with *ensure* and
*guarantee*, which promise more than most systems deliver.

Judge a claim against what might be true later, not only what's true today.

For security specifically, there's a formula that survives an incident: a feature
"helps with security" or "is designed for security". A feature that "prevents"
something is falsified the first time it doesn't.

| Recommended | Not 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. | Our product is faster than ExampleCorp's product. |
| Using our security product is part of an overall strategy that helps prevent account takeovers from phishing attacks. | Our security product prevents account takeovers from phishing attacks. |

When you do make a performance claim, name the data behind it.

## Recommendations: must, should, can

Source: https://developers.google.com/style/prescriptive-documentation

Match the modal to the strength of the requirement, and don't blur them:

| Meaning | Word | Example |
|---|---|---|
| Required | *must*, or an imperative | "Do the following before you continue." |
| Recommended | "We recommend...", "Google recommends..." | "We recommend a dedicated service account." |
| Recommended and generally recognized | *should*, which the guide says to avoid: it blurs required and recommended | "You should use a strong password." |
| Optional | *can* | "You can also use approach B." |
| Expected outcome | plain present tense | "The process returns 10 items." |
| Possible outcome | *might*, *can* | "The process can take about 30 minutes." |

Don't write *should be* to describe how something actually is. Say whether the
state is required, produced by the system, or conditional.

| Recommended | Not recommended |
|---|---|
| Ensure that the button conforms to the size guidelines. | The button should conform to guidelines. |
| The column of the data table that the filter operates on. | The column that the filter should operate on. |
| Perform the following steps. | Here's what you should do. |

## Outcomes

Source: https://developers.google.com/style/prescriptive-documentation

State what happens, not what you hope happens. The guide distinguishes an
expected outcome (plain present tense) from a possible one (*might*, *can*).

Extension: where a result depends on something the reader controls, name the
dependency in the same sentence.

## Future features

Source: https://developers.google.com/style/future

Don't document or pre-announce a feature that doesn't exist yet. This holds even
for harmless-sounding mentions of what's planned. Describe what exists.

## Timeless wording

Source: https://developers.google.com/style/timeless-documentation

Words like *currently*, *now*, and *latest* date the text and imply the reader
knows an earlier version. The present tense already carries the meaning. The full list, and the exception for
prose about a change at a point in time, are in `word-list.md`.

## Third-party products

Sources: https://developers.google.com/style/excessive-claims and https://developers.google.com/style/other-sources

Comparisons date badly and read as disparagement. Describe what your own thing
does and let the reader compare. Link to a third party's own documentation
rather than restating it.

## Third-party content

Source: https://developers.google.com/style/other-sources

Don't copy anyone else's text, images, code, logos, or speech; it risks
copyright. This covers documentation, books, blogs, videos, dictionaries,
encyclopedias, Wikipedia, open source docs, and anything on GitHub, whose
licenses vary by repository. Paraphrase the idea in your own words and link to
the source. Quoting a definition verbatim with a citation attached is still
copying.

## Verified versus assumed

Extension. Verified, reported, and assumed are three different claims: verified
means you checked it yourself, reported means a tool or a person told you, and
assumed means you inferred it. Say which one each claim is; a summary that
mixes them forces the reader to re-check all of it.