v3 documentation is honestly unusable from the ground up

[bfla]

Describe the issue

Your team asked for feedback so here it is. I've been using AWS for 10 years now and absolutely loved it. One of its best features is the JavaScript SDK. The documentation for v2 was absolutely wonderful and incredibly easy to use. I would give them an A+ in terms of the quality, ease of use, and time efficiency for engineers using them. It's one of the main reasons why as a CTO at multiple companies, I chose AWS over GCP and happily spent hundreds of thousands of dollars on AWS products choosing it over competitors like GCP and Azure. You guys rock!

I love AWS and I'm trying to be constructive here but I'm not going to sugar coat it: The current documentation for version 3 SDK API is god awful from the ground up. The current v3 docs are frankly some of the worst documentation I've ever seen for any API ever. I know it is a work in progress but at this point I have not read a single page in the documentation that is actually helpful or even close to the level of quality and usability that the old docs were.

As it stands now, I feel like the v3 API is not really ready for professional use in an enterprise software setting. I couldn't in good faith ask my engineers to use its documentation knowing that it would impede their daily work and make their jobs harder. Here is a concrete example...

Virtually all of the new documentation that I've seen looks something like this. I don't know about you, but to me as a consumer of the API this information is at best useless and at worst very frustrating. If I wanted this sort of information about the API's internal implementation details, I could read the source code. It is clearly computer generated and not meant to be read or consumed by human engineers. It's simply regurgitating the implementation details of the API using obtuse TypeScript classes which make no sense to the external engineering teams using the API to complete their day-to-day work. I literally spent an hour today trying to figure out how to make a trivially simple AWS API call. As it stands, all of the v3 documentation that I've seen reads this way. Tasks that should take 30 seconds take 30 minutes to figure out. If I were grading it in terms of helpfulness, usability, time-efficiency for my team, and overall quality I'd give this documentation a D-.

In contrast, the old documentation is wonderful. It looks like this. I can simply click on the AWS Service, Control+F to search for the keyword I'm looking for and in less than 10 seconds find the correct API method. It is clearly written by humans and tells engineers exactly what they need to know to accomplish the tasks they care about. I can click on the high-level AWS API methods and see clear, human-readable explanations and examples which lay out the API using human-readable examples and explanations. I don't have to navigate my way through multiple pages to find what I'm looking for. In two clicks and 10-30 seconds, I can find exactly what I need to know, complete the task that I'm trying to complete, and move on with my day. The old docs were A+ quality. I love them. Whoever wrote them did excellent work that saves my team and thousands of other engineers hours on a weekly basis.

Here is another example of documentation which is pretty useless and time-wasting to me as a user. Lots of verbose marketing-speak language that is completely unhelpful for engineer-facing documentation. Then the bulk of the page is devoted to generic, irrelevant explanations about how promises, callbacks, and async/await work in JavaScript. No information whatsoever about the how to call the API hooks I need to call to finish my work today. Reading through this page was a complete waste of my time. Where is the information that I actually need? I have no clue.

I know most technical teams hate writing documentation but it has to be done. Writing code is more fun but human-written docs are far superior to this low quality, computer-written stuff. Good documentation is absolutely crucial for an API like this that thousands of engineers will be using on a day-to-day basis. It doesn't matter how good the code or features are if users are confused about how to actually use it.

Anyway, I know this is a work in progress and really appreciate that your team is working hard to build a great API! So I'm sharing this feedback honestly in the hope that it will help improve things.

Links

https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Neptune.html https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-neptune/index.html https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-neptune/index.html

[RanVaknin]

Hi @bfla ,

I sympathize and understand your concern. The reason you see more and more auto-generated code is because the SDK teams moved away from owning documentation. Now, each service owns their own documentation (or rather doc writers that are being assigned to a service), and through Smithy we generate documentation for each service.

I will keep this issue in our internal records and bring this up in our next planning meeting. This won't be only an SDK effort but will involve service teams and doc writers and will take time.

If you have any specific questions regarding how-to-use or bug reports, you can always write us here on Github, as we monitor this repo daily and try to answer and help as many people as we can.

Thanks again for your feedback, Ran

[MYoung25]

@RanVaknin, thanks for bringing this up

@bfla,

I really appreciate your thorough feedback and examples, and I want to assure you this has not fallen on deaf ears. I am actively exploring ways to improve the sdk-js-v3 API reference and I'll keep you updated as the path becomes clearer. Again, thank you for your feedback as it helps us prioritize what matters most to our customers!

Best,

Michael

[1oglop1]

It usually takes me at least 4 times longer to understand something in JS documentation compared to boto3 docs which are plain simple and shows the input and output https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html#S3.Client.upload_fileobj

While in JS docs it shows the input and there is a link to another page containing the output type which links to the page of the parent type... etc. I am usually not interested in this because IDE can tell me the same thing. What I really need to see is a simple example of a call and its response.

[bradisbell]

Another completely useless documentation page: https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-polly/interfaces/synthesizespeechcommandoutput.html

$metadata: Metadata pertaining to this request.

Cool. Tells me nothing. Absolutely nothing about the response data for speech synthesis. Fortunately it's pretty easy to figure out with a debugger, but I expect much more from AWS on this. A significant part of my business lately has been figuring out your SDKs because my clients (who are developers and long standing AWS users) have had trouble doing so. We would all rather be building real products than figuring out the docs. Plenty of the information is also flatly inaccurate. It's too bad the new docs page doesn't allow me to flag it as such, like the old did.

[bradisbell]

Search is bad too. Trying to search for a command input property, DisplayLanguageCode, leads to nonsense results about signatures... looks like stuff that isn't even a public API.

[kuhe]

About search:

Due to the size of the AWS SDK for JavaScript v3, the amount of TypeScript source code and our selected documentation provider (TypeDoc), we cannot include the entire codebase in one TypeDoc generated website.

You currently have to be within a specific package to be able to search its contents. To search for DisplayLanguageCode, you would have to be in the pages for Translate Client.

We are still working on a fix for this limitation.

About SynthesizeSpeechCommandOutput:

The SynthesizeSpeechCommandOutput is a constructed generic type due to the streaming mixin and the documentation parser is not picking up its hierarchy correctly. We will work on fixing this. For the time being, refer to the underlying output type described in SynthesizeSpeechOutput.

---

Recent improvements

We have recently released a few documentation improvements.

https://github.com/aws/aws-sdk-js-v3/pull/4478

• Each AWS Service client readme now contains a list of operations supported by that client, and links to the API doc page for each. Example (at bottom of readme)

https://github.com/aws/aws-sdk-js-v3/pull/4486

• Code examples, where available, have been added to the JSDoc comment block of Command classes. Example
• Note: examples are not available for some SDK operations.

https://github.com/aws/aws-sdk-js-v3/pull/4510

• Where modeled/declared by the service, thrown Errors are listed in the Command class JSDoc. Example

Additional improvements are being worked on by @MYoung25 and will follow.

[MYoung25]

@bfla, @1oglop1, and @bradisbell

I am excited to share that, today, we released a dev preview of the new API documentation for AWS SDK for JavaScript v3 based on your and other customers' feedback. Please let us know your thoughts on the new documentation by providing feedback. We have a list of outstanding issues to address before our new documentation enters GA.

Thank you again for sharing your feedback.

[bodelia]

Not a direct comment on the docs here but related to global usability of the AWS-SDK v3.

I feel like there are tons of very small differences between v2 and v3 in the syntax but also in the global logic on which the v3 is built that make it very complex to use (and to migrate to).

For example, initializers for most packages :

import { S3 } from 'aws-sdk';
new S3({
    accessKeyId: 'example',
    secretAccessKey: 'example'
});

now is

new S3({
    credentials: {
        accessKeyId: 'example',
        secretAccessKey: 'example'
    }
});

This is definitely not a big change but just to find the right syntax took me hours and the docs were definitely not helpful (ended up finding a solution on SO).

And this is one of the minor(est) changes.

Another quite annoying change is that everything we want to run against aws is now wrapped in a command that must be sent with the client.send() command. That in itself is not really blocking (despite making the code more verbose) but in the transition, we lost features and possibilities.

For example, to get an s3 object, we could do In V2

s3.getObject(params)

and then use it both as a stream or as a promise

s3.getObject(params).promise() s3.getObject(params).createReadStream()

In v3 Now everything must be a promise and a stream at the same time

const command = new GetObjectCommand(input);
const response = await client.send(command);
const stream = response.Body // readableStream

To have a promise, we could simply promisify the readableStream from the body which is relatively easy to do.

But the other way around is not possible, we are forced to manage the Promise and once it's resolved, it seems the implementation of the ReadableStream returned in the response.Body is not the same as the one returned in the V2 with .createReadStream() function (still trying to figure that one out, some issues with async iterables and other stuff).

So all in all, I'm just complaining a bit and trying to figure out this v3 and how to migrate to it but it really seems difficult now.

A potential good improvement would be to have a side-by-side comparison between v2 and v3 for each clients and how different features are implemented in both and how to migrate from one to the other.

Another is to have links in the v2 docs to the v3 identical feature. v2 docs were filled with useful code examples while the v3 is not yet referencing much.

[MYoung25]

Thanks to this, and many others', feedback. Our new API Documentation has now replaced the TypeDoc-based documentation!

[github-actions[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs and link to relevant comments in this thread.