GoogleCloudPlatform / GoogleCloudPlatform/samples-style-guide
Guide Structure Change: Sample Apps vs. Snippets
- Dominant language
- HTML
- Stars
- 13
- Forks
- 17
- PR merge metrics
- No merged PRs in 30d
Description
## Background
There are multiple types of samples. At a high level, there are narrowly focused snippets and deployable/executable sample applications. Most of the guidelines do not apply to sample applications.
We need a way to help folks the use the style guide understand:
1. What kind of sample are they creating/reviewing. We may keep the simplified set of 2, or we may want to go with a more granular list (e.g., snippet, pattern, app, notebook).
2. Which of the guidelines apply to them
## Proposed change
1. Add definitions of sample types to the style guide
2. Add a mechanism to separate guidance by type
For (2), there are several options:
* **Annotated**: Modify the guidelines to indicate which sample types are applicable
* **Duplicated**: Duplicate the guide and add maintenance overhead to keeping them in sync
* **Normalized**: Duplicate the guide and include common text/guidelines from factored out files using Hugo shortcodes
| Category | Annotated | Duplicated | Normalized |
| -------------- | ---------- | ------------| ------------|
| Maintainability | ✅ | ❌ | ⚠️ |
| Evolvability | ❌ | ✅ | ⚠️ |
| Usability | ⚠️ | ✅ | ✅ |
| Discoverability | ✅ | ⚠️ | ⚠️ |
This table evaluates our options on 4 dimensions:
* **Maintainability:** Ease of guideline authoring & tooling maintenance
* **Evolvability:** Is it hard to change the guidelines, or allow guidelines to fork to special casing the sample types
* **Usability:** Can sample developers easily consume the guidelines
* **Discoverability:** Can developers identify the guidelines they should use
Contributor guide
Assessment
This issue has not been assessed yet.