Missing documentation on S3Client, poor all-around documentation

[bradisbell]

Describe the issue

Years after raising this issue, the documentation is still not useful.

Suppose I want to instantiate a new S3Client? How am I to do that? What config is required? Let's check the docs...

1. Google for AWS JS SDK S3Client...
2. Navigate to https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/.
3. Large section of NPM installation, yeah we know how to do that, scroll on for constructor signature...
4. See "S3Client Operations" section... maybe it's in here.
5. [scroll... scroll...] Nope, not seeing it...
6. Maybe I search for constructor in that section... nope, not there either.
7. Back at the top section there are links for Installation, Configuration, etc., let's try that. NOPE, those uselessly go to some generic landing page for the whole SDK. Go back.
8. Ctrl+F, constructor... nope, no results there either.
9. Dig, dig, dig, find "code examples", maybe that shows it... NOPE, those just leave the constructor option empty.
10. Find more code examples, NOPE those don't use the client, they use the whole SDK.
11. Oh look, AI generated abstracts... none of which are relevant... worse than useless, taking attention away from actual information...
12. Give up, write rant on GitHub with the hope AWS cares to fix it for everyone.

A serious question... How do you expect anyone to actually use your documentation? The last time this came up, there were a multitude of excuses posted about how you structure teams and SDKs internally. None of that matters to us developers who just want to find what we're looking for.

In the 25 years of doing this, I have never ran across documentation in such a poor state. Your services and this SDK is used by millions. Can you imagine the amount of time and resources you could save humanity by just fixing the documentation? This bad documentation is probably requiring a nuclear power plant's worth of energy in the excess ChatGPT-et-al queries just to figure out how to instantiate something, because the documentation is not forthcoming. Can we just get this fixed, without the nonsense? What if I send a cake? A dozen dozen donuts for the intern who takes a week to knock this one out.

Please, just take a step back, look at this problem from the perspective of a non-'azon developer, and fix it.

Links

https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/

[bradisbell]

Here's a mockup with one way this could be solved. As simple as documenting the constructor and its parameter(s).

[aBurmeseDev]

Hi @bradisbell - thank you for taking the time to provide the feedback on our API Docs. Your frustration is completely valid and you've highlighted some usability issues that need to be addressed. Let me break down the main concerns you've raised:

Key Issues mentioned:

• Basic constructor information is difficult to find
• Navigation structure is confusing and circular
• Search functionality isn't surfacing critical information
• Code examples lack complete implementation details

While we do have several resources available:

• The Developer Guide covers all the basics including SDK setup, configuration and code examples
• Client configuration and constructor type information is included at the bottom of the page
• Code examples with implementation details are provided in every command page, for example: GetObjectCommand.

However, I recognize that these resources aren't intuitive to find or navigate for new users. This is precisely the type of usability issue we need to address.

We will look into following improvements:

• Making constructor information and basic client setup more prominent
• Improving the navigation structure to be more intuitive
• Enhancing search functionality
• Providing more complete, practical code examples
• Reducing clicks to reach essential information

In the meantime, here's the direct information about instantiating an S3Client: https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/#configuration

For comprehensive guidance, you can also refer to our Developer Guide here: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html

Thank you again for bringing this to our attention.

[bradisbell]

@aBurmeseDev The purpose of creating this issue was so that an AWS dev would fix the documentation for everyone, not to get some ChatGPT response. But, I'm glad you pasted that AI fluff here because you've helped illustrate the problem.

The Developer Guide covers all the basics including SDK setup, configuration and code examples

No, it doesn't. You have one singular code example for browser usage, and nowhere does it indicate the constructor type for S3Client.

https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/javascriptv3/example_code/web/s3/list-objects/src/App.tsx

Client configuration and constructor type information is included at the bottom of the page

If you're going to rely on AI to reply to people, you should at least test your links. This link is broken. Try it. You'll see that you get redirected to https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/#configuration.

In any case, there is no indication on the page at https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/ that S3ClientConfig should be passed in as the constructor, as mentioned in the issue. That's the whole problem.

[aBurmeseDev]

Thanks for your reply. I want to clarify that I'm personally addressing your concerns as AWS team member, not using any AI assistance. Let me break down each of your concerns with references:

The Developer Guide covers all the basics including SDK setup, configuration and code examples

No, it doesn't. You have one singular code example for browser usage, and nowhere does it indicate the constructor type for S3Client.

The Developer Guide covers:

• Getting started with Node, Browser and React Native
• Setting up SDK
• Client configuration and constructors
• Setting credentials in Node and Browser
• Work with AWS Services: how to create client requests, handle responses, logging calls.
• Code Examples Scenarios for most, if not, all services.

---

Client configuration and constructor type information is included at the bottom of the page

If you're going to rely on AI to reply to people, you should at least test your links. This link is broken. Try it. You'll see that you get redirected to https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/#configuration.

I believe there may be some confusion here. I link I shared (https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/#configuration) for client configuration and constructor type is the correct link and destination.
See screenshot:

---

In any case, there is no indication on the page at https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/ that S3ClientConfig should be passed in as the constructor, as mentioned in the issue. That's the whole problem.

The S3Client page at https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/ mentions the constructor type in two different locations. See screenshot:

Top banner:

S3ClientConfig:

Please let me know if there are any other concerns that need clarification.

[kuhe]

Suppose I want to instantiate a new S3Client? How am I to do that?

import { S3Client } from "@aws-sdk/client-s3";

const client = new S3Client();

What config is required?

You can instantiate a client with no arguments, but at the least, credentials and region must be provided in a config file or as environment variables if not to the client in JS code. I describe configuration fields here: https://github.com/aws/aws-sdk-js-v3/blob/main/supplemental-docs/CLIENTS.md. There is a section for S3 on this page too.

How do you expect anyone to actually use your documentation?

Although you rejected the developer guide earlier, the constructor call can be found in step 2 at the same developer guide: https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started-nodejs.html#getting-started-with-node-js-add-code.

The API reference that the issue focuses on is a separate set of documentation that is more like a dictionary (for lookup), rather than an introduction.

Can you imagine the amount of time and resources you could save humanity by just fixing the documentation?

No.

Can we just get this fixed, without the nonsense?

I believe the information is already present and as accessible as possible. Searching "aws sdk javascript" from this homepage (https://aws.amazon.com/) brings you to the same developer guide, with its first example being one of how to instantiate the S3 Client.

What if I send a cake?

I don't know what would happen to it.