GoogleCloudPlatform / GoogleCloudPlatform/samples-style-guide

Guide Structure Change: Sample Apps vs. Snippets

Open
#105 6 comments 0 reactions 1 assignee Claimed by @grayside View on GitHub
guideline: needs work type: feature request
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

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.