No idea why he's getting downvoted but megabytes of GIFs absolutely don't belong in a code repo. Author could have just put a screenshot in there put the video inside the github .wiki.git repo.

EDIT: didn't think I have to clarify this, but when I say put a screenshot, I mean "A"(1) screenshot, if necessary.

Even the screenshots don’t belong in the code repository, there’s another 2MB in this instance. I think you can still get the README to embed images from elsewhere? And if not, just link to it, “screenshots over here”.

The compromises being made in bloating repositories because GitHub presents the README as project info rather than at least allowing you to separate it are painful.

What happens when the URLs referenced by the README stop existing (domain expiry)? What about when the project is forked? What happens when I want to look at old documentation locally?

Why should the entire project not be subject to version control? It's a well established industry best practice.

Reproducible documentation is just as important as reproducible builds.

There's likely a strong argument to be made for Git sub-modules though i.e. putting the documentation in a sub-module.

This particular content isn’t documentation so much as marketing material—part of the shift GitHub has foist upon us in what a README is. But even were it documentation, that needn’t belong in the same place. This is the wisdom of rjzzleep’s suggestion of the wiki repository, an auxiliary Git repository that GitHub already creates for you.

why don’t megabytes of gifs belong in git? you can use things like git-lfs if you don’t want the file updated with every change.

A screenshot or two, sure. And maybe chrismorgan's point could have been, well, perhaps expressed more gently. :) But the general point about multi-megabyte image files that are only there to enhance the README file perhaps not being ideal to have in your code repo, and something you could have on a separate non-repo page that goes into more detail, seems pretty reasonable.

I thought that embedding videos only works in issues and PRs, not Readmes?

Even when GitHub didn’t support embedded videos, large GIFs are awful enough that I insist that they had no place in READMEs, whether internal or external to the repository. In that time, it was far better to make it a link to something external.