Dynamoose: [QUESTION] - Could you add to the docs examples like the ones recommended by AWS architects?

[AllanOricil]

Summary:

I really got confused about how to use this lib after watching this video https://www.youtube.com/watch?v=DIQVJqiSUkE
The way mongoose and dynamoose are written makes people model their nosql database in terms of entities, declaring one schema and model per entity, like we usually do with sql databases. I saw a lot of examples of people declaring the Hash Key as id, which uses uuid library to generate a unique hash. At first I thought it was the right way of doing it, but after watching the video above and reading the docs I understood the bad impact it can cause in terms of number of partitions and read/write throughput.
Maybe it is good if in the doc you give examples of what not to do, and the reason behind it.
This website has a lot of good examples and it is written by the author of the youtube video: https://www.dynamodbguide.com/working-with-multiple-items
And here is the doc for how to denormalize a Relational Database and use DynamoDB
https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/bp-modeling-nosql-B.html

[fishcharlie]

What exactly is the question here?

[fishcharlie]

@AllanOricil Got it, looks like you updated the title of this issue. So I'll address that question.

So this has been an ongoing discussion for a while. @MickL brought this up a while ago. And it lead to some good discussions and I think some good improvements since then.

There is a balance here that I think is important. For one, Dynamoose shouldn't have the goal IMO of educating people on how to use DynamoDB. The purpose of Dynamoose is to give users a good modeling system for DynamoDB, inspired by Mongoose. And so the documentation should be primarily focused on that. Which currently, it is.

A good comparison here is that Express.js documentation doesn't have details about how the internet or HTTP requests work. It's expected that if you are using Express.js that you understand what GET, POST requests are, along with how requests and responses work. It's expected you understand ports and how they work at a basic level.

I know the question might be It's so easy to add this to the documentation, why don't you do it?. And while that might be true, it's one more thing to maintain.

I think I'd be open to linking out to other resources maybe in the FAQ section, to other good DynamoDB resources. But I'm not sure it should be this projects responsibility in the docs to educate users on DynamoDB. I think the focus should remain on Dynamoose and how it works.

I will note, we have some best practice notes in the documentation already, like in Scan it encourages users to look into Query first. There are also subtle things in the documentation that encourage best practices, such as having Query page be before Scan.

There is also a balance here between being an easy on ramp for Mongoose users and using DynamoDB best practices. This project started as being 100% focused on a Mongoose alternative for DynamoDB. Single table design, and some of the Scan documentation I mentioned above, are new concepts to Dynamoose. I think the fact that it was an easy on ramp for Mongoose users was key to the initial success of this project.

I do recognize that things need to adapt, and I don't wanna be a project maintainer that kills a project because I don't adapt and I'm set in old ways. But I have to be realistic about my time. We currently have a lot of issues that I haven't gotten a chance to get to yet. I've just recently found time to review PRs and hopefully gonna find time to put out a release soon. So it's not like I have a lot of time to really make a plan and maintain a lot of best practice documentation.

I'll close with this. PRs are welcome. If you want to help contribute to the project, it's open source, you are more than welcome to. Even adding code snippet examples to the documentation, that doesn't require a lot of maintenance, I don't think I'd deny that PR.

I want this project to be amazing, and I'm dedicated to it's success. But time is the biggest factor here. The more contributors like you that can help improve the project, the better it'll be.

If I had to choose between fixing some of the other bugs you mentioned, or the other bug issues currently raised, and adding these examples to the documentation, I'm going to focus on fixing bugs. There are a lot of great DynamoDB resources out there, whereas there is only one Dynamoose. So fixing bugs is just a higher priority. It's not like users can't get the information they need elsewhere. So it's just level of priority here.

Feel free to create PRs! And I hope I answered your question.

[AllanOricil]

I understand your point, and I agree now. Thanks for spending some time explaining the above.

[fishcharlie]

@AllanOricil Of course! Glad I could answer your question. 😃