This repository has been archived by the owner on Apr 26, 2024. It is now read-only.
Synapse's documentation source files are split into two organisational systems and is confusing #11274
Labels
A-Docs
things relating to the documentation
O-Occasional
Affects or can be seen by some users regularly or most users rarely
S-Tolerable
Minor significance, cosmetic issues, low or no impact to users.
T-Task
Refactoring, removal, replacement, enabling or disabling functionality, other engineering tasks.
Z-Cleanup
Things we want to get rid of, but aren't actively causing pain
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
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.
docs/
folder to match that of the website.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.The text was updated successfully, but these errors were encountered: