When https://www.netlifycms.org/docs/beta-features/#folder-collections-media-and-public-folder was introduced the main intended use case was to allow saving media files in the same folder as the entry under the constraint different entries don't share media files.
Since then we've added support for specifying per collection and per field media_folder and public_folder. We also allow media_folder to be either a relative path or an absolute path which can cause confusion: decaporg/decap-cms#3654 (comment).
We've also added templating and cascading for media_folder and public_folder which is not documented at all (decaporg/decap-cms#3670 (comment)).
We should document all of these changes and provide examples for each scenario.

Important

Make it clear to what the media_folder is used for (specifying where to save the file in the repo) and what public_folder is used for (specifying how to output the file path in the frontmatter).