dabit3 commented 4 years ago

In the docs, we currently cover how to use the APIs as well as how to use the CLI to create AWS services.

What is currently missing is more in depth content around common use cases. These use cases could be things like how to model data for popular data access patterns, how to deploy a custom domain to the amplify console, how to manage state when using Amplify DataStore, etc.

This content could be structured as tutorial-style guides for things that are commonly asked questions and common uses cases when working with Amplify.

I propose a new Resources section in the main navigation with subsections for particular categories of content.

Starting off, Resources could stand alone with a few pieces of subcontent:

Resources Managing state in React with Amplify DataStore Using DynamoDB in AWS Lambda Building a REST API with AWS Amplify, API Gateway, and DynamoDB How to deploy a custom domain to the Amplify console How to create custom data access patterns with AWS AppSync and the GraphQL Transform library.

As the resources section grows, we could then create subcategories for types of content:

Resources

Recipes
Reference guides
Working with Amplify Console Hosting
Community Content

swaminator commented 4 years ago

@dabit cool RFC. What's the difference between 'Resources' and 'Tutorials'?

dabit3 commented 4 years ago

I think Tutorials is a little limiting in the sense that we may way to categorize more than only tutorials in the future and will not be limited by a broader category name.

swaminator commented 4 years ago

I think Tutorials is a little limiting in the sense that we may way to categorize more than only tutorials in the future and will not be limited by a broader category name.

What about Learn? I've seen a bunch of other developer-focused products that do the same.

dabit3 commented 4 years ago

@swaminator I love Learn as a top level name, it implies exactly what we're hoping to do with this new content.

mtliendo commented 4 years ago

Learn is nice in the sense that it's broad while also serving as a recognizable goto place to see how things are done.

Just trying to draw some inspiration on what's already out there, Sara Drasner's Array Explorer comes to mind as an awesome way to drill down into what user's are trying to get at. A possible scenario would be:

I am building for _____ (web, mobile, both)
I am using with _____ (JavaScript, iOS, React Native)
I would like to explore _____ (Auth, API)
Optional: I am using _____ (NextJS, Gatsby, etc)

Once a user gets done with that flow, a curated list of Learn items would populate.

This flow would work with existing documentation since having to go through this flow to simply explore would be cumbersome.

scenario 2: Addition to the CLI

In this case the same flow as above would begin, but only when the user typed something like

$ amplify learn

The benefit of this approach is that the CLI has metadata on the type of project the user is working with, so prompts to be minimized/made for specific.

Technically, nothing is stopping this from existing as a plugin, but with it built into aws-amplify/cli it would likely be better maintained.

In either scenario, accessing a list on content would mean there'd be an open API full of resources that lives separately from existing packages. I'm imagining a submission process being where items are submitted via GitHub issues and later tagged (approved) by Amplify team members before being merged into a simple json file.

🗒️ Similar to when one first creates a component library, time would likely need to be spent gathering all existing tutorials and selecting the ones that best convey a topic (a bit of friendly competition to create high quality material)

scenario 3: 🍒 low-hanging fruit

The docs could take a more iterative approach by creating a set of tags under a Learn tab and upon selecting a tab, a set of links where one can learn would show up on a page relating to the tag. This probably isn't what this RFC is trying to accomplish, but offering that up for completeness.

dabit3 commented 4 years ago

@mtliendo this is great feedback. I like the CLI command. I wonder if it would be as simple as just opening up the Learn panel in the documentation for a v1, and then we can improve it later?

Agree with the low-hanging-fruit, would love to collaborate on an initial set of docs / links for an initial launch and get your feedback on what you think are things that are must haves or are of most importance.

kldeb commented 4 years ago

@dabit3 I'm currently on-boarding a new dev and I'm making notes for where he gets stuck. I'll be using his on-boarding as a resource for preparing short tutorials for future devs we on-board. Planning to share it with a wider audience as well.

The getting started is well documented now (you've done a great job there). As amplify grows getting quick videos and articles for different features and common use cases will be very helpful.

As an aside, the angolia search is starting to get in the way of finding information. In some cases, I know the information is there since I've read it before but I can't find the right keywords to get to it.

dabit3 commented 4 years ago

@kldeb Yes, if you can share that document it would be a great help! Thank you for that.

As far as the algolia search, thank you I'll pass this on so it can be addressed.

renebrandel commented 4 years ago

@kldeb - good feedback! We're looking into Algolia search as we speak.

jordanranz commented 4 years ago

@dabit3 this is a great idea. This could be a great "resource" for more complex and unique use cases that fit outside of getting started. I am curious how organization (product/platform/framework) would work here? Maybe each top level product can have its own Resources section? I guess if it blends together products like CLI and JS for example you'd want it at a higher level but having all of this in a single location could potentially be difficult to properly navigate and find what you are looking for.

I also can also foresee the maintenance of these sections being challenging without a set test/deploy of the code in these resources. That being said we should definitely be working towards a solution for this throughout our docs :D

glauberfc commented 4 years ago

@dabit3 what do you think about add some tutorials teaching the basics about the main technologies behind Amplify, like DynamoDB, CloudFormation, etc?

Sometimes using Amplify I feel like if I was trying to use React without have a base in JS. I mean, sometimes I get problems that I don't know how to solve because I don't have experience in the technologies behind Amplify.

I'm talking this based on this article too: https://medium.com/swlh/how-to-really-use-aws-amplify-fcb4c5ed769c

ericclemmons commented 4 years ago

I provided some feedback on twitter, but posting here for greater clarity.

When I first started learning Amplify (and even now), I'd love to reach for single-purpose recipes: Amplify by Example.

In other projects, I've reached for Next.js' examples to answer "How to do X with Next.js". Being able to answer the same for Amplify in a highly-searchable way would save a great deal of clicking through the docs.

Here are some sample questions I've gathered from my notes since I started using Amplify:

How do I change the Auth redirect URI in production?
How do I link both a registered user via email to their Google/Facebook login?
How do I get @models by X (vs. just id)?

dabit3 commented 4 years ago

Here is some great feedback from @weisisheng as far as some ideas around what a multi-tenant example could look like.

@glauberfc I think some basic examples around these service would be helpful. Some ideas:

How Lambda works (returning data from a function, enabling cors, giving access to other resources, the event and context objects)
DynamoDB, GSIs and modeling additional data access patterns for a base type (what's going on under the hood)
What is created in API Gateway when a REST API is creaetd
Some basics around VTL and customizing GraphQL resolvers

cyrfer commented 4 years ago

I would have benefited greatly from guides like:

using cognito user pools created outside of amplify project (by API and other modules).
using the team.json file to pass custom CF parameters for each environment.
writing custom cloudformation stacks for asynchronous workflows (e.g. StepFunctions).
passing outputs from amplify managed CF stacks to custom (or enhanced) cloudformation stacks.
setting Appsync's default auth mode to be cognito user pools, but add an additional auth mode for asynchronous workflows.
using @aws_iam on fields and types when using the @function instead of @model for query/mutation fields from asynchronous workflows, when AppSync's default auth type is set to cognito user pools.
using @aws_cognito_user_pools on fields and types when using the @function instead of @model.
how to deploy from Jenkins
how to deploy to various AWS accounts

mtliendo commented 4 years ago

Would a next step be to compare what examples the docs offer, with what examples the community is asking for?

From there we could select resources for each item to get curated list of examples. It would also serve as a backlog of content that needs to be expounded upon. Thoughts?

mrichman commented 4 years ago

I’d love to see a complete example using Vue.js that exercises the various APIs, such as Auth, Storage, API, etc.

Side note: Sign-in has been particularly challenging for me, since the built in Authenticator component doesn’t use a token than can also be used with a Cognito authorizer against an HTTP API. I’ve had to revert to the Cognito hosted UI since that returns a token with the proper scopes.

mtliendo commented 4 years ago

I wonder if in cases like these, where we are trying to provide documentation on a service but in the context of a different framework, that the docs themselves wouldn't benefit from being in a different format. Something like below?

sample

dabit3 commented 4 years ago

@mtliendo agreed, we could use something like what's at https://docs.amplify.aws/lib/auth/getting-started/q/platform/js#option-1-use-pre-built-ui-components

rpostulart commented 4 years ago

I would like to see more how the security part of everything is working. No this is abstracted away sometimes, but it is always good to see that there is documentation available where you have full details.

jhw commented 4 years ago

Hi, some quick thoughts on Amplify.

As an intermediate AWS user (== plenty of experience with Lambda, API Gateways, hand crafted Cloudformation YAML), I really want to like Amplify (as I can see it is doing a lot of powerful stuff under the hood) but the thing that is really off- putting is how much stuff (eg) amplify auth does for you, with precisely zero explanation.

Let's focus on authentication. So this is really important if you're ever going to run your own SaaS. But Cognito is frankly very hard to understand and a bit of a mess (User pools ? Identity pools ? App clients ? Auth servers ?) even if you have a degree of AWS experience.

Posts like this don't help -

https://www.integralist.co.uk/posts/cognito/

In the end I found these three very useful -

https://itnext.io/aws-cognito-example-using-react-ui-and-node-js-rest-apis-part-1-cognito-setup-5597acb02db4?gi=86fac0fb4913

https://itnext.io/aws-cognito-example-using-react-ui-and-node-js-rest-apis-part-2-react-ui-app-with-redux-6cc22610affe?gi=7aa18df7278c

https://itnext.io/aws-cognito-example-using-react-ui-and-node-js-rest-apis-part-3-jwt-secured-rest-apis-e56d336ce306?gi=c4c870c49883

(Cognito has a hosted auth UI? Who knew?!)

But then the hosted UI might not be the answer either -

https://medium.com/collaborne-engineering/replace-cognito-hosted-ui-d7619d037036

So - amplify auth is very very temping because you can see that whatever it's doing, it just works.

However. The amount of stuff that gets generated for you on the Cloudformation side. Tons of template, lots of embedded lambdas - yuk.

Similar on the JS side - the overriding feeling is "don't worry about it, just import this giant JS thing and everything will work fine"

That's probably fine as a sort of Trojan- horse approach to getting devs hooked on AWS services, but very unappealing to me who likes to understand (even if only to a very small extent) what's happening under the hood.

I like to know that if I need to modify some aspect of Cloudformation, I can do that - not that I'm stuck because the Amplify CLI doesn't support the particular option I want.

My general approach to AWS development is to try and find a snippet of YAML that does what I want/need, confirm it works, and then build from there.

The value that Amplify offers me is that is clearly represents "best practices" in terms of server side patterns in some areas (auth, graphql) - but I won't be using it until I better understand precisely how those patterns work.

So for the minute I'm reduced to generating an amplify auth project, then painstakingly working from the ground up with the Cloudformation it generates, to better understand what is really happening. Painfully slow, but I'll get there.

Really what I'm trying to do is to "liberate" the underlying topology patterns from the autogenerated stuff.

But some posts on precisely what patterns and resources the different aspects of Amplify (auth, graphql) create and use would be very welcome, I suspect not just to me.

PS the CDK is very good in this respect in that it feels like it helps you manage Cloudformation complexity, without giving up anything in the way of control - Amplify would do well to channel some of that CDK spirit

mrichman commented 4 years ago

@jhw I agree 100%. There's entirely too much "magic" with Amplify CLI commands.

I do all my infrastructure using SAM, and then I use Axios to hit my API Gateway HTTP APIs (I'm not using REST). I do use the JS functions, but it's limited to Auth and Storage, and I roll my own aws-exports.js for its configuration. The only downside of this approach so far has been the fact that I'm forced to use the Cognito hosted UI. The Amplify Cognito UI controls don't use the same authentication flow that the hosted UI uses. As a result the tokens that come back when using the UI controls lack sufficient scopes to invoke my APIs. I can certainly live with hosted UI if I have to.

mtliendo commented 4 years ago

1776 is created to address REST specific doc improvements and suggestions. While there is some overlap with what Nader is proposing, it's more meant to attempt parity between the graphql docs and the REST sections.

sammartinez commented 4 years ago

I just wanted to callout if you guys can look into what External Resources similar to what is within Redux Saga. This would be nice. I know that you have something similar @dabit3 for awesome-amplify (couldnt find the link to the repo) but I see this being helpful for all levels

dabit3 commented 4 years ago

Merged https://github.com/aws-amplify/docs/pull/1942

aws-amplify / docs

RFC: Guides on the docs #1661

🗒️ Similar to when one first creates a component library, time would likely need to be spent gathering all existing tutorials and selecting the ones that best convey a topic (a bit of friendly competition to create high quality material)

1776 is created to address REST specific doc improvements and suggestions. While there is some overlap with what Nader is proposing, it's more meant to attempt parity between the graphql docs and the REST sections.