Improve documentation examples for Elastic Transcode

[foresmac]

The existing examples have 200 lines of configuration struct and 4 lines actual code to execute a job. It would be great if a few examples where included that showed what is minimally required to actually kick off a job, and what, if any, defaults are used when certain parameters are omitted.

Additionally, it would be really useful if there was a more detailed explanation of the various configuration parameters in the SDK docs. IME, it's a little difficult to directly translate from the Elastic Transcode documentation (which is a little dense on its own) to the samples in the Go SDK docs.

[jasdel]

Thanks for the feedback @foresmac. Improving documentation is one of our goals. Are there any specific types of transcoding jobs/pipelines or other operations examples would be the most helpful?

In the meantime using the transcoder console to create test jobs would be helpful since the SDK operation input parameters match the console pretty closely in this case.

[foresmac]

@jasdel Thanks for the pointer; once I create a job in the console, is there a way to get the config copied so I can use it to build a struct programmatically? If so, it would be a nice pointer to add to the docs. ;)

[jasdel]

Sorry, ElasticTranscoder does not have a method to extract the pipeline/job config from the console.

If you'd like to give feedback requesting this feature you can do so on the ElasticTranscoder Console page. In the bottom left corner is a black and white "Feedback" button.

[foresmac]

@jasdel Cool, will do on the feature request. :stars:

I guess if I could describe my particular goal at the moment, you might have a specific suggestion. I feel this is probably the 80% case if I had to guess:

I have an S3 bucket where all the original files are uploaded. I have an S3 bucket where all the transcoded files go. I have a pipeline already set up for this. And I'm using a pre-set for transcoding options. I think the only other thing I need to specify is the output key format. I believe other than that I just want ET to just do its thing. What would that look like?

[foresmac]

Just adding some notes as I work my way through the docs and the source to figure out how to using the SDK:

In the example to create a job, nil is passed to New() when creating the service. As best as I can tell, at a minimum I need to pass an *aws.Config with at least credentials set up. Probably the 99% case is doing so via ENV, which it appears is done automatically by the default config. But, you need to pass a region name in as well, and there's no default for this, so you'd need something like what is detailed here:

svc := elastictranscoder.New(&aws.Config{Region: "us-east-1"})

[foresmac]

All over the example, every string is wrapped in a custom type like so:

aws.String("Example String")

But the "Getting Started" docs show just passing strings into structs. Can this be safely ignored?

[lsegal]

But, you need to pass a region name in as well, and there's no default for this,

@foresmac we default to AWS_REGION, actually. Our getting started guide has more information on this in the configuring section:

https://github.com/aws/aws-sdk-go/wiki/Getting-Started-Configuration#setting-the-region

It's very common to pass nil to your service constructor, which will initialize using aws.DefaultConfig.

[foresmac]

@lsegal I missed the part after "not set by default" where it says "reads in a ENV variable". Sorry.

[foresmac]

What I think the minimal params are:

• JobInput
• PipelineID
• Output (or Outputs, but we're talking one file to another)

What is minimally needed for JobInput:

    Input: &elastictranscoder.JobInput{ // Required
        AspectRatio: "auto", // Should this be "Auto" or "auto"?
        Container:   "auto",
        FrameRate:  "auto",
        Interlaced: "auto",
        Key:        "s3_filename.mov",
        Resolution: "auto",
    }

If it's all auto, is this the default? Or would &elastictranscoder.JobInput{Key: "s3_filename.mov"} work?

What is minimally needed for Output:

    Output: &elastictranscoder.CreateJobOutput{
        Key:             "transcoded_filename.mp4",
        PresetID:        "1351620000001-000010", // Generic 720p H.264
        Rotate:          "auto",
        ThumbnailPattern: "-{count}-{resolution}",
    },

This is the best I could discern from the console settings. I did request the options to copy the configuration from a job to be added to the console as requested.

[foresmac]

Oh, JobInput might require setting the JobContainer, but I haven't been able to confirm what this setting is. Maybe the console infers it from the input key from S3?

[lsegal]

@foresmac if your goal is to perform a basic transcode job, you might want to take a look at some of our other sample projects using Elastic Transcoder. The JS implementation might be a good start. It's not in Go, but should provide good information on what values should be set and to what-- members should map 1:1 to our Go structures. Also, our API docs should also be answering questions like "should this be auto or Auto" / "is this the default". Those should be in the docs themselves. Please let us know if that's not the case.

(Note that all strings are pointers and must be passed in as aws.String(...). This should be documented in our Getting Started Guide as well as our examples for each operation)

[foresmac]

@lsegal Yes, it looks like this example more or less confirms what I outlined above. When you say "should be in the docs themselves", which docs are you referring to? Separate Elastic Transcoder API documentation?

As I noted on the confusion on whether a Go string literal or aws.String was required, the Getting Started guide shows examples of aws.Config using string literals as a counter example. So, maybe it's ok there but not in params for services?

I'm really not trying to be obtuse, but you can see how when I need to look at four different places (Getting Started guide, SDK godocs, example projects for other SDK languages, and I presume Elastic Transcoder API documentation) for documentation it gets hard to be sure if I understand things correctly.

[lsegal]

As I noted on the confusion on whether a Go string literal or aws.String was required, the Getting Started guide shows examples of aws.Config using string literals as a counter example. So, maybe it's ok there but not in params for services?

aws.Config does not take string pointers, but all service operations do. Using a string literal simply would not compile, since the type is a *string. We have examples for every service operation in our API documentation that should show how to pass parameters in. You don't need to use aws.String(), but at the very least, you cannot pass a string literal, since they are pointers. If you already have string variables holding these values you could use &myvar instead. @jasdel is working on updating our guides to show examples in our "Making Requests" section, which should clarify.

I'm really not trying to be obtuse, but you can see how when I need to look at four different places ... it gets hard to be sure if I understand things correctly.

Eventually we will be able to consolidate some of our documentation into a single spot (godoc doesn't really like rich "guide style" documentation), but perhaps I can explain what each doc is used for, since you shouldn't need all of them at the same time.

• Getting Started Guide - this document should be used to get a general idea of how to configure and make basic requests with the SDK. If it's your first run with the SDK, you probably want to be following this in addition to the API documentation, since this doc focuses solely on the syntax and behavior of the library itself, and not on the behavior of our AWS services.
• SDK godocs (API docs) - this should be your primary stop for reading about the service you're trying to use. Everything in Elastic Transcoder's API reference is in our own API documentation, including what values can be passed in to which structures. For example, JobInput mentions using "auto" in a number of places, and these are the same places that you would find them in the regular API docs. Our example operations show all required fields with a // Required comment, so if you do not see that then the field is optional and has a server-side default. We could do a better job of pointing this out in the textual documentation (the non-example portions), but for now you can identify required params with the required:"true" tag on the member.
• Service Developer Guide (Elastic Transcoder for example) - this document extends far beyond the scope of the SDK. If you're getting started with a service and want to understand the concepts, you should probably give this doc a read since it will give you a basis for vocabulary and other terminology. You should not need this document for coding, though in some cases, services may supply helpful samples that you might want to look out for.

Basically, the API docs should cover 80% of what you need after you've ramped up on SDK basics and service vocabulary. Note that all of the documentation text in our API docs for services come from the service documentation itself-- in other words, you will find the exact same information in Elastic Transcoder's "API Reference": http://docs.aws.amazon.com/elastictranscoder/latest/developerguide/create-job.html#create-job-request-input

If you're having trouble comprehending our API documentation for any reason, I would suggest visiting the API reference documentation linked above and supplying feedback, since all of our content comes directly from those pages.

Hope that helps.

[foresmac]

I've been making successful requests with the following minimal parameters:

    params := &elastictranscoder.CreateJobInput{
        Input: &elastictranscoder.JobInput{
            AspectRatio: aws.String("auto"),
            Container:   aws.String("auto"),
            FrameRate:   aws.String("auto"),
            Interlaced:  aws.String("auto"),
            Key:         aws.String(key), // the "filename" in S3
            Resolution:  aws.String("auto"),
        },
        PipelineID: aws.String("09583757687362-xxxxxx"), // Pipeline can be created via console
        Output: &elastictranscoder.CreateJobOutput{
            Key:              aws.String(key + ".mp4"),
            PresetID:         aws.String("1351620000001-000010"), // Generic 720p H.264
            Rotate:           aws.String("auto"),
            ThumbnailPattern: aws.String(key + "{count}-{resolution}"),
        },
    }

[foresmac]

Getting Started Guide - this document should be used to get a general idea of how to configure and make basic requests with the SDK. If it's your first run with the SDK, you probably want to be following this in addition to the API documentation, since this doc focuses solely on the syntax and behavior of the library itself, and not on the behavior of our AWS services.

SDK godocs (API docs) - this should be your primary stop for reading about the service you're trying to use. Everything in Elastic Transcoder's API reference is in our own API documentation, including what values can be passed in to which structures. For example, JobInput mentions using "auto" in a number of places, and these are the same places that you would find them in the regular API docs. Our example operations show all required fields with a // Required comment, so if you do not see that then the field is optional and has a server-side default. We could do a better job of pointing this out in the textual documentation (the non-example portions), but for now you can identify required params with the required:"true" tag on the member.

Service Developer Guide (Elastic Transcoder for example) - this document extends far beyond the scope of the SDK. If you're getting started with a service and want to understand the concepts, you should probably give this doc a read since it will give you a basis for vocabulary and other terminology. You should not need this document for coding, though in some cases, services may supply helpful samples that you might want to look out for.

The above would be perfect to put into the main README, I think.