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

[amirhhashemi]

📚 Subject area/topic

Reference

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

• https://docs.solidjs.com/solid-router/reference/data-apis/use-submission
• https://docs.solidjs.com/solid-router/reference/data-apis/use-submissions

📋 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

[LadyBluenotes]

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).

[LadyBluenotes]

@amirhhashemi I feel like you improved the reference docs, the only thing required is creating the guide (which there's another issue for). I'm going to close this for that reason

[amirhhashemi]

@LadyBluenotes I haven't addressed this Issue yet.

I have many issues with how data mutation primitives (action, useSubmission, and response helpers) are documented and I can't focus on improving a single page. I think the content is misplaced in many places and "fixing" a page requires moving some content to another page. Maybe 4 or 5 pages are involved.

I haven't worked on it mainly because it's a lot of work. Perhaps it's better to create another issue to discuss these issues that I have and if I could convince you to move in that direction I can fix it in one PR.