datamodeling/functional-units - page too opinionated
udf2457 opened this issue · 2 comments
Coming from the perspective of a developer briefly skimming through the Prisma docs for the first time to see if Prisma might be a good fit for my project, I need to pass comment that datamodeling/functional-units is far too opinionated.
You spend at least a quarter of a page (if not more), lecturing the reader on why you think they should not be using database functions / stored procedures (e.g. "Here's why you might not want to program your database!")
You do not consider valid reasons why a user might want to use functions / stored procedures (e.g. prevent SQL injection attacks, manage business logic etc.). Instead you provide all sorts of highly questionable arguments against database functions / stored procedures, most of which don't hold up to any real scrutiny and are based on highly subjective opinion of the author rather than objective facts.
Meanwhile, you provide exactly zero examples or insight on that page as to how someone might use Prisma in conjunction with database functions / stored procedures.
Please guys. Focus the docs on what they should do. Demonstrating and documenting what your software can (and cannot) do. Save the opinions for mailing lists, forums, Slack or wherever it is that you informally discuss Prisma.
Its all really off-putting and just makes me want to look elsewhere.
Hey @udf2457, thanks for sharing your thoughts. We really appreciate the feedback and had a really good discussion internally about the points you bring up. There are a few points I wanted to try to clarify that might help put some of the choices we made into context.
To start off, Prisma's Data Guide is a separate project from Prisma's documentation. So while the documentation is focused on the Prisma-specific intersections with these ideas, the Data Guide is a more general resource. The goals of the Data Guide are to provide platform-agnostic guidance on working with databases with both hands-on and conceptual components. Currently, I'd say the majority of the content in the Data Guide are either tutorial-based (as in Setting up a local PostgreSQL database) or functional overviews (as in Understanding and using transactions in PostgreSQL).
That being said, you are absolutely correct in identifying the Data Modeling section as a departure from this type of content. It takes a much more opinionated tone than the other content and was a bit of an experiment with a more prescriptive approach to data modeling. We may have gotten the balance off between providing guidance to readers who are new to databases and looking for help and being overly prescriptive in how to think about databases. We stopped producing content for the Data Modeling section partly because we weren't confident that opinionated guidance was best suited for the library of content we're focused on producing.
We're discussing how best to address these issues because, ultimately, we think you're right. I think the confusion between the goals of the Data Guide and the docs is one area we should work to clarify. The context of the data modeling section versus the rest of the content in the Data Guide is another boundary we should more clearly demarcate and explicitly talk about.
As for the specific comments you had about the advice in that article, I think for now we'll focus on trying to establish some context around the piece rather than editing it directly. I think that there's value in preserving the author's perspective as long as it's clear where general advice ends personal thoughts begin. Please share your thoughts though and let us know if you think we're on the right track.
Just a quick note -- the reason there's a quarter-page of "why you wouldn't want to do this" in Functional Units is that the other eight sections take the view that business logic or programmatic data manipulation belongs in the database by default, absent a reason to put it higher up the stack.
As with any architectural consideration, there are always situational or subjective pros and cons to be weighed. Going all-in on the "pro" side without acknowledging these nuances would do the reader an immense disservice.