chore: rename markdown doc for convenient browsing

[benelan]

Renamed all of the markdown files in /doc from index.md to readme.md so that they are easily browsable on GitHub.

find . -name 'index.md' -type f -exec sh -c '
for f; do
    mv "$f" "${f%/*}/readme.md"
done' sh {} +

[joelparkerhenderson]

Thanks for the PR. Is it the case that you would broadly want this kind of effect (i.e. GitHub rendering) for all files named index.md in all repos for all users?

If so, I'd like to ask GitHub to add the feature for everyone. This is because there are a bunch of files like this, such as thousands of blogs, that all use *.md files, that could benefit from automatic rendering.

[benelan]

I don't think there needs to be any changes on GitHub's end. For consistency, the convention is that only readme.md renders.

What if there is a directory with both index.md and readme.md files, which would render? And if there are a bunch of markdown files and no readme, then which one renders? Would it be alphabetical?

Or if someone doesn't want their markdown to render for whatever reason, that could be a breaking change for them.

I think rendering any markdown file would cause more confusion than it would solve. Especially when people can achieve the desired goal by naming their file-to-render readme.md.

[joelparkerhenderson]

For consistency, the convention is that only readme.md renders.

Yes, that's the problem here. What you're describing is what Microsoft is trying to change because of bias. What you're seeing is the effect of Microsoft's employees applying a set of their own internal non-standard rules to one kind of filename, rather than using any open standard or enabling an open source author to choose the outcome. Microsoft is actively aiming to change the bias going forward.

This is because the bias causes problematic issues for repositories that need to work across a variety of systems, such as for Microsoft enterprise customers, especially ones with legal/political/organizational/technical needs for specific files and file names. Some examples are creators of repos who want to use non-English languages, or who want readme.md rendered as markdown not as GitHub Flavored Markdown, or who want to use non-Microsoft formats or markdown adjucnts.

The best solution (IMHO) is to have developers who care enabled to make their own choices about rendering. This is where Microsoft leaders want to head because it's better for inter-organizational teams and diverse enterprises such as multi-national companies.

What if there is a directory with both index.md and readme.md files, which would render?

The index.md file. When a user goes to a directory path, then the widespread convention among most worldwide organizations and most open source projects is to render index.* not readme.*. Microsoft had this exact same kind of issue years ago with IIS and eventually harmonized on index.*.

If you look at other organizations and tools, such as many popular webservers (e.g. NGINX, Apache, Caddy, etc.) and many popular blog tools (e.g. Jekyll, Hugo, Zola, etc.) then you'll see that the tools have special handling that favors file names index.* over readme.*. Microsoft leadership states that they want to align with the internet conventions in order to empower diversity of developers and development pipelines such as with Azure.

If you would like, I'm happy to take your request to Microsoft people to see ifhow they may be able to look at this, with the outcome being rendering more kinds of files from markdown to HTML here on GitHub. Any ideas or thoughts about this?

[benelan]

Yeah, I guess I should have specified that readme.md is the GitHub convention; I'm aware of the ubiquitous use of index. I never ran into any issues due to GitHub's convention, but I can definitely see the use case for allowing people to choose what gets rendered.

It could even be specified in a config file, e.g. .github/rendering.yml. In my opinion, we would want to keep the default as readme.md, at least until the messaging gets across.

That being said, since this repo is on GitHub, I still think it's worth following their convention for now. If/when they install the enhancement, it is really easy to change back using the script I included above.

[joelparkerhenderson]

Your way is better with rendering.yml. Want to ask the GitHub folks? Generally they are very good about considering ideas like these, especially because your point helps reduce bias of cross-cultural communication, and also improves capabilities for lots of developers. I see your idea as win-win-win.

That being said, since this repo is on GitHub, I still think it's worth following their convention for now.

Well, the repo is involved in a lot of places, including webservers, bookmarks, and blog pipelines that use index.md as a specialized file-- so it's kind of a choice between the repo working with every open source developer and open source tool and open source convention, or forcing the repo to break because of Microsoft's hardcoded bias.

The previous two times I've seen this happen, MIcrosoft did the right thing, and fixed the naming areas. So I'm hopeful Microsoft will listen to your idea and take it seriously.

In the meantime, to get you want you want ASAP, could it work OK for you if your script copies index.md to readme.md? This means two files, which isn't totally ideal, yet does get you a pragmatic solution for now. What do you think?

[benelan]

Ah, I didn't realize the repo is used in other applications that require the filename to be index.md. After taking another look, there are links to index.md in the repo itself as well, which would need to change.

I think that's another good use case for allowing the user to choose their rendering preference. In my opinion, having duplicate files is a bit overkill, so I can close this PR. I have my fork that I can use in the meantime.

[joelparkerhenderson]

OK good. If you've heard of "Chesterton's Fence", that's the kind of idea of the repo links that you correctly mention. (Or if you're new to the fence, it's a nifty shorthand)