docs: Separation of /docs - repo and archive #15161

As previously discussed (well put by @laanwj here), there is a problem with the structure of the documents in /doc. The main problem is that the documents are meant to be read in two different contexts:

1. On Github or in a cloned repo
2. In a downloaded archive

The latter also has been packaged by the build process into a slightly different file structure.

This situation makes it very hard to write good documentation that is on point in both contexts, and I strongly believe the docs need to be separated somehow.

I'm not sure which strategy is best though. Should the build process be tweaked or can the problem be solved with just file names? I imagine other GitHub projects may have similar problems, how are they usually solved?

I think you misunderstood me a bit. I don't think this is a general issue with the documents, just with README.md in doc/. This document is used in two contexts which conflict.

The straightforward solution would be to split it up; keep the current doc/README.md as a ToC for our documentation folder (for people browsing it on github) and create a separate document that is packaged as "getting started" by the build system.

Ok, thanks for clearing that up. I agree that the doc/README.md is the main problem, but that other files in /doc have related problems. Example: I believe README_windows.txt is only meant to be read in the context of an archive, but being located in doc and being named as a README, I think some readers may read it out of context.

However, since doc/README.md is the main problem, I'll close this issue and rephrase in a new one.