See MikeNakis.CommonFiles.README.md

Explanation:

PEARL: Visual Studio suffers from a monstrous, insidious bug where the spell checker goes haywire if you have two files with the same name in the solution.

To work around this bug, one has to make sure to give unique filenames to all files in a solution. This is possible with the vast majority of files, except for some, because there are some stupid tools that require certain fixed filenames for certain things.

One such stupid tool is GitHub, which requires the README file to be called README.

The solution to this problem is to prefix the filename of the README file with the name of the project, i.e. MyProject.README.md. (This has the added benefit of also making it easier to locate among editor tabs.) Then, we must have a README.md file for exclusive use by GitHub which only contains a link to MyProject.README.md. (This is what this README.md file is, plus this whole text explaining why we are in this preposterous situation.)

• It is not possible to copy MyProject.README.md as .github/README.md, because then all relative links in it would be broken.

• It is not possible to create a symbolic link called README.md pointing to MyProject.README.md, because GitHub is so special that it refuses to follow the symbolic link; instead, it renders the content of the symbolic link itself, which is just the target filename.