Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Content]: Clarify useSubmission(s) Documentation to Emphasize Actions Over Form Submissions #1024

Open
amirhhashemi opened this issue Jan 16, 2025 · 1 comment
Labels
in progress Someone is currently working on the issue.

Comments

@amirhhashemi
Copy link
Collaborator

amirhhashemi commented Jan 16, 2025

📚 Subject area/topic

Reference

📋 Page(s) affected (or suggested, for new content)

📋 Description of content that is out-of-date or incorrect

The problem

The useSubmission(s) documentation focuses a lot on form submissions, which I think is misleading. It introduces useSubmission mainly as a tool for handling form submissions. However, as I understand it, even when using useAction to invoke an action, the submission details are still available through useSubmission(s). This means useSubmission(s) is not just for forms.

The documentation also says:

It's important to note that useSubmission requires the form method to be post otherwise it will trigger a browser navigation and will not work.

This makes it seem like useSubmission(s) depends on form submissions, but the need for method="post" is actually about how actions handle form submissions, not about useSubmission(s) itself.

This becomes a problem when trying to remove the Creating the action section. In a related issue, I suggested removing it because it seemed unrelated. But when I tried to remove it in a pull request, I realized it was the only part that explained the link between submissions and actions. This forced us to awkwardly clarify that submissions are really about actions.

If users get halfway through the useSubmission(s) reference page without realizing it is mainly about actions, then the documentation is not clear enough.

Proposed Solution

I suggest rewriting the useSubmission(s) reference page from the beginning through the end of "Creating the action" section.

Instead of focusing on form submissions, the documentation should explain useSubmission(s) as a way to access an action's invocation/submission details/state. This way, we don’t need to say things like "To trigger a submission, actions can be used," because it will already be clear. Also, this would better describe what useSubmission(s) actually does.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

@amirhhashemi amirhhashemi added the pending review Awaiting review by team members. label Jan 16, 2025
@LadyBluenotes LadyBluenotes removed the pending review Awaiting review by team members. label Jan 16, 2025
@LadyBluenotes LadyBluenotes removed their assignment Jan 16, 2025
@LadyBluenotes LadyBluenotes added the in progress Someone is currently working on the issue. label Jan 16, 2025
@LadyBluenotes
Copy link
Member

Hey @amirhhashemi, thanks for bringing this to our attention. I chatted with some people on the team and for the sake of avoiding being opinionated here, we all agree that removing the focus on forms is for the best.

With that being said, you can remove the information in a PR for this since we will need to create a guide that addresses what we will be removing here (and elaborating on it all).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
in progress Someone is currently working on the issue.
Projects
None yet
Development

No branches or pull requests

3 participants