feat(AIP-8): clarify clients AIPs should benefit (#1114)

Without clear guidance on the types of clients AIPs should
benefit, it is unclear to an AIP author what the criteria of
a good AIP is.

This clarifies the guidance, and implicitly expand the
scope of AIPs beneficiaries from just end-users to all
clients that user may use to interact with the API.

Author: toumorokoshi

aip/general/0008.md

@@ -7,22 +7,65 @@ placement:
   order: 40
 ---
 
-# AIP Style guide
+# AIP Style and Guidance
 
 AIP stands for **API Improvement Proposal**, which is a design document
-providing high-level, concise documentation for API development. The goal is for
-these documents to serve as the source of truth for API-related documentation at
-Google and the way API teams discuss and come to consensus on API guidance.
+providing high-level, concise documentation for API design and development. The
+goal is for these documents to serve as the source of truth for API-related
+documentation at Google and the way API teams discuss and come to consensus on
+API guidance.
 
 AIPs are most useful when they are clear and concise, and cover a single topic
 or inquiry well. In the same way that AIPs describe consistent patterns and
 style for use in APIs, they also _follow_ consistent patterns and style.
 
 ## Guidance
 
-AIPs **must** cover a single, discrete topic, and **should** fundamentally
-answer the question, "What do I do?" with actionable guidance. AIPs **may** also
-cover what _not_ to do, but **should not** cover _only_ anti-patterns.
+- AIPs **must** cover a single, discrete topic, and provide clear, actionable
+  guidance.
+- AIPs **must not** duplicate or contradict guidance in another AIP.
+- AIPs **may** also cover what _not_ to do, but **should not** cover _only_
+  anti-patterns.
+- If AIP guidance is conditional (e.g. a design pattern such as Jobs), the
+  guidance **must** clearly explain under what conditions the guidance should be
+  followed.
+
+Guidance contained within an AIP **must** be beneficial to one or more
+types of clients or their authors, including but not limited to:
+
+- Asset inventories which can be used to audit and analyze resources.
+- Command line interfaces for exploration and simple automation.
+- Custom controllers (e.g. auto-scalers) which poll live state and adjust
+  resource configruation accordingly.
+- [IaC][] clients for orchestration and automation of multiple resources.
+- Recommendation tools which provide guidance on which APIs are useful for
+  specific use cases, and how to use them.
+- SDKs to interact with an API from a programming language, often used heavily
+  for data-plane operations.
+- Security orchestration, automation, and remediation tools.
+- Simple scripts to automate or orchestrate tasks.
+- Test frameworks.
+- Tools that operate on resource data at rest.
+- Visual User Interfaces for visualization and one-off manual actions.
+- Users.
+
+Examples of improvements include:
+
+- Requiring new proto annotations that enable more descriptive interfaces on
+  clients (e.g. requiring `singular` and `plural` on a `google.api.resource`
+  annotation).
+
+AIP guidance **must not** be a significant detriment to a client's usability or
+implementation difficulty, or maintenance difficulty.
+
+Examples of detriments include:
+
+- Introduction of a non-uniform pattern in a standard method such that all
+  clients must introduce additional code without sufficient benefit (e.g. List
+  behaves like this *except* for resources that start with the name Foo).
+- Renames of well-established fields for minor improvements in readability (e.g.
+  rename `expire_time` to `lapse_time` since `lapse` is a common term in my
+  service).
 
 While the length of AIPs will necessarily vary based on the complexity of the
 question, most AIPs **should** be able to cover their content in roughly two
@@ -190,12 +233,27 @@ subdirectory); this ensures that the link works both on the AIP site, when
 viewing the Markdown file on GitHub, using the local development server, or a
 branch.
 
+## Rationale
+
+### Designing for a broad set of clients
+
+API guidance, similar to any software, is most beneficial when there is a clear
+purpose and target beneficiary.
+
+The beneficiaries of improved API design are users. These users interact with
+APIs via a variety of clients, depending on their use case as enumerated above.
+
+API guidance must in turn consider the impact broadly across these clients.
+
 [aip-1]: ./0001.md
+[Infrastructure as Code]: ./0009.md#iac
+[IaC]: ./0009.md#iac
 [protocol buffers]: https://developers.google.com/protocol-buffers/
 [rfc 2119]: https://www.ietf.org/rfc/rfc2119.txt
 
 ## Changelog
 
+- **2023-05-20**: Increase API guidance scope to include broad set of clients.
 - **2023-03-30**: Removed appendix, added rationale and history to the template.
 - **2020-02-18**: Specified reverse chronological ordering for changelog items.
 - **2019-08-23**: Added guidance for internal AIP links.