Amplify Resolver Section & Readability/Audience Suggestions

[dklein1211]

Today I joined the open hours discord call to talk about this topic and they pointed me here to give the feedback.

I used to be a kb admin for over 7 years and wrote a lot of docs in my time. One thing that I struggle with regarding the AWS docs is that the audience they are speaking to seems to be pointed at a high level developer. For people like myself learning Amplify I find it really hard to find the information I need in a language that I can understand at a lower level. In addition visual aids are supposed to help fill in gaps if you have to speak to a higher level audience for the lower level audience. I found that the visual aids dont provide enough information to fill in the gaps.

To resolve this issue it would be nice to have access to the full code of a template project that illustrates whatever subject is being talked about. That way even if the language is complicated a person can reverse engineer the full code example stored in some git repo to get a complete view of how to do something. I find myself wishing many times that if their was a repo of the whole topic then I could figure it out faster.

Take for instance Amplify VTL resolvers. It is such a complicated thing to do that it took me way to long how to figure out how to do the following.

1. How to make a extend a VTL resolver
2. The limitations of a req and res resolver function IE only 1 DynamoDB action per req or res.
3. How to debug a VTL resolver via the $util.log function.
4. How to override the data source of the resolver function so that it points to the right table <--- This is not in your docs and is a common thing people want to do.
5. How to test the pipeline via AppSync Queries

Some of this is documented but its not all in a centralized place to put it together quickly. And some information is only available on the old docs. I get the impression that the people writing these docs either has a very surface level of what these systems do and possibly getting the bullet points from a high level developer and just building the doc from that or is the high developer that assumes the reader knows a lot more about all the products and thus leaves out a lot of lower level information. Thus entry level devs or devs new to the products are going to spend way more time trying to figure out how to do stuff. In my case I struggle to read docs and lean on the visual aid or code source to fill in the gaps and that visual aid aka a repo of a project that implements the subject matter doesn't really exist. Then I have to lean on an outdated ChatGPT data model which is in 2021 to sometimes have some knowledge of what to do or to better explain parts of what I am trying to do.

To summarize

1. The resolvers section could be better organized and have more information and more examples on how to set them up.
2. Write part of the docs to lover level developers
3. Provide better visual aids and access to full project examples of how something is done.
4. A lot the docs are very singular in how to do something but its rare that there are example of how to do real world common problems like. How to do minor validation for a creation mutation resolver. Such as query a table of users, check if the data to save has an email address and if so check if any users from the query have the same email address, if so error out. Or in a delete mutation resolver, when deleting a user who has a 1 to many relationship with a phone numbers table. If you delete the user and need to update the phone number in the phone numbers table attribute from assigned to unassigned. Simply how to do basic chained real world back end actions.

[dklein1211]

Another example would be to look at how to create a lambda resolver. Look at these articles and notice there is no reference to the step by step process in the main resolver article on HOW to build out a lambda resolver function. Their are other sections about resolvers in other places. These all need to be under one place and have references in articles that link to the main source.

Main
https://docs.amplify.aws/cli/graphql/custom-business-logic/#lambda-function-resolver

Actual Process
https://docs.amplify.aws/guides/api-graphql/lambda-resolvers/q/platform/js/#creating-the-graphql-api

[dklein1211]

If you want I am more then happy to sit down with an editor to point out additional improvements to the structure of an article and where certain information should be included and hash out a potential checklist for future docs.

[dklein1211]

another example where not enough information is given. In the following article under the Add a custom resolver that targets an AWS Lambda function where it says add the function as an Appsync data source in the stacks Resources block. For a new user trying to set this up they have no idea what you are talking about or where that is. If you include a path or more verbose instructions on where that is and what it is and explain what it is doing this article would give the reader more knowledge.

This example of not enough information is everywhere.

https://docs.amplify.aws/cli-legacy/graphql-transformer/resolvers/#add-a-custom-resolver-that-targets-a-dynamodb-table-from-model

[cwomack]

@dklein1211, thank you opening this issue and for the thorough feedback!

[renebrandel]

Hi @dklein1211 - Thanks a lot for your feedback on our documentation. We really appreciate you taking the time to share your thoughts, especially with your experience as a former knowledge base admin.

I wanted to let you to know that we're actively working on a big revamp to make our documentation more "jobs-to-be-done" based with step-by-step instructions that are easier to understand.

We're also taking your feedback about the resolvers section to heart. We'll make sure to provide more information, examples, and real-world use cases, covering topics like extending VTL resolvers, debugging, and more.

We really appreciate your patience and support as we work on these improvements.

If you want I am more then happy to sit down with an editor to point out additional improvements to the structure of an article and where certain information should be included and hash out a potential checklist for future docs.

This would be amazing! Feel free to reach out to me at [renbran at amazon dot com] - let's coordinate some time to chat.