Skip to content
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

Open
3 tasks
anoadragon453 opened this issue Nov 8, 2021 · 2 comments
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

Comments

@anoadragon453
Copy link
Member

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 anoadragon453 added z-maintenance A-Docs things relating to the documentation T-Task Refactoring, removal, replacement, enabling or disabling functionality, other engineering tasks. labels Nov 8, 2021
@anoadragon453
Copy link
Member Author

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.

@DMRobertson DMRobertson added S-Tolerable Minor significance, cosmetic issues, low or no impact to users. O-Occasional Affects or can be seen by some users regularly or most users rarely Z-Cleanup Things we want to get rid of, but aren't actively causing pain and removed z-maintenance labels Aug 25, 2022
@anoadragon453
Copy link
Member Author

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

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
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
Projects
None yet
Development

No branches or pull requests

2 participants