Whither documentation?

[skyzyx]

(Context: I was a founding member of the AWS SDK team in 2010.)

Hey guys. I know that this is a preview and everything, but documentation is always worth 50% of your grade. If you have flawless code and no docs, you still get an F. That, and this SDK is in the aws org instead of the awslabs org — that has a meaning built into it.

We all saw what happened when the AWS SDK for PHP v2 shipped with no documentation — all because the team was trying to ship by Saint Reinvent’s Day. It was an unmitigated disaster, and a blemish on the AWS reputation.

The documentation for this SDK really, really needs a lot of love. Some of it appears correct. Some is outdated and points to the old v1 SDK. Lots of documentation is straight-up missing. I know that management may still view thorough documentation as a nice-to-have, but it isn’t — documentation is critical enough that it should be viewed as having equal importance as the lines of code produced.

Could you guys please dedicate at least a full sprint to actually writing prose content that isn't auto-generated? Since most of the documentation is generally added in the upstream service models before it makes its way down to you guys, some of it is good/useful, while a fair amount of it is virtually unusable. It would be a really wonderful thing for the rest of us to have solid — if not, amazing — documentation available.

I know that you guys have a bajillion services to manage SDKs for, and auto-generation is the easiest path to follow. I am absolutely certain that you guys are doing the best you can with the resources you have available. But, having said that, the current state of documentation is not meeting the minimum bar of usability.

I know that Amazon has a penchant for building things like the top & left. But that's unequivocally wrong-headed. The team needs to strive for the bottom & right. Raising the bar, and thinking like an owner, and having a bias for action, and all that jazz.

I've been an AWS customer for over a decade, including 4 years in AWS Developer Productivity and Tools. AWS has always sucked at this, but SDK-specific documentation is the area that needs the most love, across all SDKs (IMO).

Anyway, thanks for listening.

[jasdel]

Thanks for the feedback @skyzyx. We agree focused documentation can be very helpful to users. Are there specific areas of the SDK that could use the most initial focus? Such as:

• SDK configuration from external sources, e.g. shared config/credential file
• SDK credential configuration
• Enabling detailed request logging
• Modifying the SDK's request lifecycle
• How to use XYZ service

Or are you looking for more examples and details for how to use specific services? If so it would be great to hear the use cases and which services.

[shawnsmithdev]

IMHO, having a high quality result in godoc is the most important part of documenting a go library. High level docs ex. in Github Wiki or README.md is important too, but godoc is usually first thing folks look at when they ask "How do I do X".

[skyzyx]

I'm less concerned with the specific services (in general).

• The static-language SDK team generally follows the pattern led by the Java SDK which is creating input model objects, then passing them to request methods.

• The dynamic-language SDK team generally follows the patterns led by the PHP SDK and Boto which is passing a generic object {…} to a request method. The PHP SDK (as an example) further simplifies this by providing a simplified interface which executes the request directly upon calling the request method.

In both cases, the service-specific patterns themselves are pretty-well shared across all AWS SDKs and even the AWS Unified CLI Tools. Good work here. ❤️

---

The part that is causing the most trouble are the things that are specific to this SDK, and how it works compared to other SDKs.

• SDK configuration from external sources, e.g. shared config/credential file
• SDK credential configuration

Yes, but for more than out-of-the-box use-cases.

For example, I have a project that is a Golang Lambda function which has the ability to check your AWS account for certain bits of information. This works perfectly well in my own team's account, but how does my company configure cross-account access enabling the Lambda function to talk to another team's AWS account? We can configure IAM roles, and I know that assuming access is something we can do, but I have no idea how to do it with this SDK.

This is a fairly common use-case in large/complex organizations.

• Enabling detailed request logging

Always handy, and definitely yes, but this isn't something I'm running into at the moment.

But definitely yes.

• Modifying the SDK's request lifecycle

I've done a TON of this with the PHP SDK (v's 1.x, 2.x, and 3.x) in the past, and Guzzle is definitely a really amazing underlying HTTP client for PHP. I'm not running into this yet as I'm starting to work with Golang a lot more, but this is definitely the kind of thing that you should survey your users about to learn which kinds of use-cases should get love first. This is definitely worthy of a dozen tutorial pages in your documentation.

• How to use XYZ service

Coming back to this topic, mostly no. But what matters to me are the things that are specific to this SDK.

The project I paused work on in order to respond to this GH issue is that I'm working on a replacement PoC for https://ec2instances.info, to make it use the AWS Pricing API. I'm proofing out a system for fetching, storing, and presenting the data — and learning Golang as I go.

So when I come across something like aws.JSONValue, and I see:

“JSONValue is a representation of a grab bag type that will be marshaled into a json string. This type can be used just like any other map.”

That seems to be great, except that how do you navigate through the deeply-nested map[string]interface{} objects which are children of the aws.JSONValue object?

type PriceResponse struct {
    InstanceType map[string]interface{}
}
// make request and handle pagination…

results := []PriceResponse{}

for _, entry := range page.PriceList {
    results = append(results, PriceResponse{
        InstanceType: entry["product"].(map[string]interface{})["attributes"],
        // …
    })
}

Examples would be very, very nice. While many users of this SDK may be well-versed in Golang, some of us are not quite there yet. There's a lot of trial and error when you're learning a new language and SDK at the same time. :)

Everybody knows how to work with EC2 and S3 because those are some of the oldest services and there are a bajillion tutorials about them. I'd love to see more focus on examples and actual explanatory prose behind how to think about problem solving for a particular service. Detailing the nuances of how this SDK works compared to the others is important as well.

Lastly, the Pricing API straight-up points to the wrong SDK.

Thanks again for taking the time here.

[Chanonry]

Just had a moan at your technical support. I was trying to enable acceleration on an S3 bucket using the v2 SDK. Nice guy but says its not his job.

Fair enough but how about some docs that are more than just an api reference ? How about doing the stuff to help us actually use the sdk. I have spent 2 years using the python sdk and it is bad enough but this is just impenetrable. You have to remember most developers have less than 2 years experience and they are going to be your future clients so give them some support

[jasdel]

The SDK has started to migrate the v1 SDK documentation and developer guide for the v2 SDK. These can be found currently, https://aws.github.io/aws-sdk-go-v2/docs/, and we are working on having formatted docs available

[skyzyx]

Excellent news. Thank you.