Improve documentation for post update hooks and update hooks to clarify distinction

Problem/Motivation

In Drupal 8 there are two ways for a module to run configuration/schema/database updates. One is by creating a hook_update_N hook in your module's .install file. The other way is new to Drupal 8 and is to create a hook_post_update_NAME hook in your module's .post_update.php file.

Problems:

• The documentation for these hooks do not mention the other at all.
• The update API documentation does not mention even the existence of post_update hooks.
• The only public discussion I could find about this is this DrupalCon Vienna talk from 2017, which mentions a "do's" and "don't"s list for what to put in update hooks, but no clear rules around it.

Proposed resolution

First, we need to establish hard and fast rules about these hooks. I don't know what they are. I generally just understand that it's not safe to put certain changes in hook_update_n(). But if it were as simple as that, then why not just use post_update for everything?