Documentation proposal: Insert Returning example

In my experience, it's a common question for new devs on DB libraries is how to handle inserts that return ids: Do you handle them as commands or queries, and similar things. In fact, I've had this question asked in company slacks a few times regarding skunk. As far as I can tell, the documentation doesn't seem to mention "Insert returning" at all, and the only time it's used in tests, it's in a case where it's supposed to exception out, so it's not even the greatest of examples.

I think that we can make onboarding easier, and cut down on questions, by putting an example of insert returning in the main documentation. I'd even be happy to write it if it'd take too much of a maintainers time.

Given the current shape of the documentation, If I was making the decision, I'd consider some the following edits:
-A single sentence addition on the Queries section, to indicate that we should use query whenever there's an expected return value, regardless of whether the operation is a pure select, or an insert.
-An actual example of an insert returning inside of query, possibly as its own section
-A mention in the command section that if one wants to insert while returning some of the values, to used query instead.

But since I am not really owning the documentation, and only volunteering some time, I'd be happy to make any/all of the three changes, or any others that might be recommended. Or you could just close this, or make the changes without me. I just don't want to go through the work if it's not in a shape that would merge.

No documentation file is named; start by locating the Queries and command sections in the repository documentation and review how database operations are currently explained. Done means the documentation clearly explains using query for inserts with returned values and includes a working insert-returning example.