Proposal: Product-specific guidelines

[grayside]

Description

Either in the existing page or a new page, add product or PA-specific guidelines. This would be a central place anyone can visit to see Sample expectations that are specific to a product. This provides a path for some sample consistency within a product space even with high turnover of contributors that have limited knowledge transfer.

I imagine a section of product guidelines where individual products are H2 headings and guidelines per product are H3 headings.

Using Eventarc as an example:

• Building Container Images: [Simplicity] Prefer jib or buildpacks to build container images, eventarc samples shouldn't teach containerization. (Note: This could be promoted to a general default sample guideline)
• CloudEvent Metadata Priority: [Idiomaticity] Prefer CloudEvent metadata over payload fields where redundant values can serve the same purpose. For example, CloudEvent time over data timestamps if the specific time of the resource update is not required
• Building Test Cases for Integration Tests: [Maintainability] Prefer using CloudEvents SDK to build events for integration testing. This may not be feasible in all languages.
• Inline Type Definitions: [Clarity] Languages without a type library should include an inline object definition with well-commented, minimal fields. The type should link to the proto and JSON-schema definition, either directly to the GitHub resource or via Cloud Docs.

Impact

Reduced design/planning overhead, increased consistency. Individual guidelines could create new work and should still go through a review process.

Challenge

Choosing whether to place product guidelines in the main guide page or a new page.

[averikitsch]

+1 for product-specific guidelines. Separate guide pages may be best to reduce cognitive load.