[PROPOSAL] Improving Client Documentation: Consolidating, Standardizing, and Testing Client Setup and Connectivity Samples

[wbeckler]

What/Why

What are you proposing?

We propose addressing the range of gaps in our client documentation by implementing the following:

1. Consolidating the client setup samples for Serverless, Managed Service, and open source.
2. Instituting continuous testing of client setup and connectivity code (e.g. [FEATURE] Add integration tests for all clients to test against Amazon OpenSearch Service and Amazon OpenSearch Serverless Service #47).
3. Adopting a common standard across all clients for feature coverage in the documentation that covers major use cases and includes sample code that gets tested continually.
4. Setting up a framework for requiring documentation by default on all issues, with clients as a guinea pig for this as a standard across the organization, similar to the Changelog workflow.
5. Moving raw markdown client documentation into the client repos, with the styled documentation showing up on the documentation website so that:
   1. Client documentation can be versioned alongside code.
   2. A client team developer is more likely to see issues and PRs related to their client’s documentation.
   3. Client repos can integrate doctest or a similar framework in a straightforward way.
6. Adopting a one-version documentation strategy for clients, that includes version differences as in-line information.

What problems are you trying to solve?

We aim to address the range of gaps in our client documentation. The code samples for how to set up clients are spread across documentation hosted by three different teams: OpenSearch Project, Managed Service, and Serverless. The evolution of clients and APIs is happening separately from the documentation, as they are in separate repositories, and there are no processes linking all of these. Due to the processes we have today, we believe it may be getting worse.

What is the developer experience going to be?

The proposed solution will improve the dev experience by providing more comprehensive and easily accessible documentation for client setup and connectivity.

Are there any security considerations?

N/A

Are there any breaking changes to the API?

N/A

What is the user experience going to be?

N/A

Are there breaking changes to the User Experience?

No, there are no breaking changes to the user experience.

Why should it be built? Any reason not to?

It should be built to ensure that our clients have comprehensive and easily accessible documentation, which will improve the overall developer experience and reduce the time and effort required to set up and connect clients.

What will it take to execute?

To execute this proposal, we will need to:

1. Consolidate the client setup samples for Serverless, Managed Service, and open source.
2. Institute continuous testing of client setup and connectivity code.
3. Adopt a common standard across all clients for feature coverage in the documentation that covers major use cases and includes sample code that gets tested continually.
4. Set up a framework for requiring documentation by default on all issues, with clients as a guinea pig for this as a standard across the organization.
5. Move raw markdown client documentation into the client repos, with the styled documentation showing up on the documentation website.
6. Adopt a one-version documentation strategy for clients, that includes version differences as in-line information.

Any remaining open questions?

None at this time.