GoogleCloudPlatform / GoogleCloudPlatform/samples-style-guide

Proposal: Define pronoun prefixes for placeholder parameters

Open
#174 2 comments 1 reaction 0 assignees View on GitHub
guideline: request type: feature request
Dominant language
HTML
Stars
13
Forks
17
PR merge metrics
No merged PRs in 30d

Description

### Description

I couldn't find any guidance in the [samples-style-guide](https://googlecloudplatform.github.io/samples-style-guide/) or an Open Issue, about whether to use the pronoun prefix `my_`, `your_` or None in samples placeholder parameters.

I found public resources such as [Google developers - Second person and first person](https://developers.google.com/style/person) and [Material Design - Style Guide - Word Choice](https://m3.material.io/foundations/content-design/style-guide/word-choice), recommending the usage of `you` and `your` instead.

@glasnt has pointed to [https://developers.google.com/style/placeholders#placeholder-text](https://developers.google.com/style/placeholders#placeholder-text) which states `When documenting an API [...] Don't include possessive adjectives in placeholders.`

[style/code-samples](https://developers.google.com/style/code-samples) doesn't specify a requirement, although it shows this example:
```yaml
image: IMAGE_URL
```

### Proposal summary

1. Define a recommended or required style. For example: `MY_`, `YOUR_` or None.
2. Add an example, e.g. in [samples-style-guide/#pattern](https://googlecloudplatform.github.io/samples-style-guide/#pattern)

### Impact

This leads to inconsistencies across the repo, which is bad practice from a User Experience (UX) perspective.

For example on Python:
[dataplex/snippets/get_entry.py#L57](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/46a0c737defcabda799c38c348bf5c62a9b84f0d/dataplex/snippets/get_entry.py#L57)
```
project_id = "MY_PROJECT_ID"
```

[iap/example_gce_backend.py#L22](https://github.com/GoogleCloudPlatform/python-docs-samples/blob/46a0c737defcabda799c38c348bf5c62a9b84f0d/iap/example_gce_backend.py#L22)
```
CLOUD_PROJECT_ID = "YOUR_PROJECT_ID"
```

### Challenge

- Training for sample creators, maintainers and reviewers will be required.
- It might require to batch update the style across all the samples in different repos, to be enforced.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.