Synapse's documentation source files are split into two organisational systems and is confusing

[anoadragon453]

As noted in #10086, part of the transition to the new documentation website was figuring out a structure for the existing documentation pages. These ended up being organised into what is now the layout configured by SUMMARY.md.

This allowed us to organise the documentation on the website, yet the source files were still left in a pile in the docs/ directory. The decision was made to not move them into directories that mirror those in SUMMARY.md, as doing so would break existing (non-permanent) links to documentation files on GitHub.

This has currently left us in a state where our documentation is split into two organisational systems, as can be seen with the documentation for the Admin API. Docs exist in

1. https://github.com/matrix-org/synapse/tree/9799c569bb481622b5882b2008a24e6c4658c431/docs/admin_api and
2. https://github.com/matrix-org/synapse/tree/9799c569bb481622b5882b2008a24e6c4658c431/docs/usage/administration/admin_api

Enough time has now passed that links to Synapse's documentation should now be pointing to the documentation website instead of the source files. Thus, it is proposed to now shuffle the documentation files such that they mirror the directory structure of SUMMARY.md/the website. Perma-links (though referencing a specific commit) to the source files will continue to work, but all other links to documentation source files (in comments, not code) throughout the codebase should be updated to point to the website instead.

• Update existing links to documentation source files throughout the codebase to point at the website instead.
• Organise files in the docs/ folder to match that of the website.
• Add a warning that several documentation source files has been moved to the changelog, to encourage external links to be updated.

Afterwards we'll only have a single system of organisation for the docs/ folder, and it'll be obvious where to look for a file when coming from the documentation website.

[anoadragon453]

I'm not sure if I realised it at the time, but URLs to doc pages are currently based on their filepath, rather than their organisation in SUMMARY.md. So moving files will break links to the documentation.

To help with this, I propose introducing stub pages in the old locations that redirect to the right place. These would be built in our CI rather than actually include the pages in docs/, as they're only really a concern for the matrix-org.github.io deployment. A file somewhere in the docs/ folder would detail what pages mapped to what.

[anoadragon453]

To help with this, I propose introducing stub pages in the old locations that redirect to the right place. These would be built in our CI rather than actually include the pages in docs/, as they're only really a concern for the matrix-org.github.io deployment. A file somewhere in the docs/ folder would detail what pages mapped to what.

Nevermind, mdbook actually supports link redirection as a feature! https://rust-lang.github.io/mdBook/format/configuration/renderers.html#outputhtmlredirect