matrix-org / matrix-org/matrix-spec
Store spec implementation guides in an appendix of the spec
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
There is a funny mix of content at matrix.org/docs.
While there isn't a formal definition of what content belongs there or not, as an m.org website maintainer I feel that the website is already torn between content about at least the Matrix ecosystem, the Matrix technology, the Matrix network, the matrix.org homeserver, and The Matrix.org Foundation. This is pretty hard to make approachable to readers.
The content of /docs is mostly "user facing" content in some way, i.e. chatters, community mods, server admins. Ignoring the legacy docs, there is also https://github.com/matrix-org/matrix.org/tree/main/content/docs/spec-guides, which is "implementer facing".
The spec by nature is also implementer facing. I think the guides would better fit into a non-normative part of the spec website.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by comparing the /docs content on matrix.org with content/docs/spec-guides in the matrix.org repository, then inspect how the Matrix specification site organizes non-normative material. Define the appendix location and move the implementation guides there, with the guides no longer living as mixed user-facing content under /docs.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100