Guide Structure Change: Sample Apps vs. Snippets

[grayside]

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

[grayside]

Here's an example of "Annotated":

[grayside]

Here's an example of "Duplicated":

.
├── _apps.md
├── _index.md
└── examples
   ├── dotnet
   ├── go
   ├── java
   ├── node
   ├── php
   ├── python
   └── ruby

[grayside]

Here's an example of "Normalized":

.
├── _apps.md
├── _index.md
├── examples
│   ├── dotnet
│   ├── go
│   ├── java
│   ├── node
│   ├── php
│   ├── python
│   └── ruby
└── guidelines
    └── linting

[amanda-tarafa]

From the options you are proposing I like the annotated one better.

But I would like to propose another option, and that is to separate the guides in "code style guide" which will apply to all types of samples, and "sample guidelines", which I think will be different enough for different types of samples that it'd be OK to keep them separate.

Even the example you are using from annotated, i.e. Region Tags, I would argue is not the same for applications and snippets. In snippets, you want a region tag per snippet. In applications, I've seen plenty of time that there's a region tag per relevant part of the application (setup, action, error handling, cleanup), so that is very common that the same application has several region tags.

Basically, the burdens inferred from your table are very different depending on how similar are the guidelines for the different types of samples, if they are very similar the burden from duplication is great, but if they are almost entirely different then "duplication" is something we can live with.

[averikitsch]

I like annotated and normalize. Would it be possible to add a "page filter" based on the annotation in order to get the benefits of normalize but with the maintainability of annotated?

I also like Amanda's proposal of a code style guide and sample guidelines, but that may be too big of a refactor.

Lastly, we might want to connect with iX to see if they have any learnings or best practices.

[grayside]

Here's a preview with some changes I made along the lines of what Amanda suggested: https://googlecloudplatform.github.io/samples-style-guide/previews/PR-129/