On a related note, should we recommend fedpkg build --scratch --srpm instead?

I was going to suggest fedpkg scratch-build --srpm for both lines.

Good suggestions, worth following.
However, a bit more work ensues,
because the surrounding prose and commands makes even less sense after that change.

I will rewrite this section to always use fedpkg,
then just mention koji and the additional options it provides in the end.

Done.
The koji Git url form is actually explained separately later in the document,
so I removed it from the scratch builds section.
No need to explain the same thing twice.

Assuming fedpkg scratch-build is the same as fedpkg build --scratch the commit actually needs to be pushed to a non-fork branch, not just committed.

"Koji-related" ?
"lower-level"

Assuming fedpkg scratch-build is the same as fedpkg build --scratch the commit actually needs to be pushed to a non-fork branch, not just committed.

I checked this now, and indeed, that's the case:

$ fedpkg scratch-build
Could not execute scratch_build: There are unpushed changes in your repo
Try option --srpm to make scratch build from local changes.

~~This is shitty.~~

~~I don't think it makes sense to push people towards this command then.
Instead, just replace the rpmbuild -bs with fedpkg srpm.~~

EDIT: Ah, I can't read.

fedpkg scratch-build --srpm works fine.

Thank you taking some time to look into this!
Looking at this a bit more comprehensively,
I actually feel that the whole Scratch builds section is not providing much value here.
As soon as a packager discovers what scratch builds are,
they are better of typing fedpkg scratch-build --help or koji build --help
than reading such incomplete and arbitrary collection of commands.

So, I switched focus a little bit:
Everything except the most common case of fedpkg scratch-build --srpm can go,
and the common case can be moved to "Package Maintenance Guide",
where it fits better.

What do you think?

(I will push the two-line change to use fedpkg scratch-build --srpm separately now,
as that seems to be uncontroversial and was the original topic for this PR.)

Hmm, I'm not convinced. It is true that those docs "duplicate" the in-built program help, but I think that they still provide value. The built-in docs are very terse, and not very well formatted, so many people prefer the web version, even if it is sometimes incomplete. Also the web version is indexed by the search engines and can be linked to. I think that a document titled "Using the Koji build system" should describe scratch builds.

My line of thinking is that Package Maintainer Docs should not attempt to comprehensively document the tools.
Each individual tool should do that in their own docs,
and the Package Maintainer Docs should concentrate on how they are all tied together to create the Fedora packaging environment.
So listing all the different options of scratch builds should go to fedpkg or koji docs.
So I went to take a look and found this:
https://docs.pagure.org/koji/using_the_koji_build_system/?highlight=scratch+build#

It is basically the same article, but of course these two have diverged from each other.
These two should be merged somehow.
Until that happens, I do not see much value in improving this instance any more,
so I will close this pull request now.