matrix-org / matrix-org/matrix-spec
New Spec Design: Error code descriptions should be indented
Nobody has claimed this yet.
- Dominant language
- HTML
- Stars
- 330
- Forks
- 150
- Avg merge
- 2h 21m
- Merged PRs (30d)
- 3
Description
https://spec.matrix.org/unstable/client-server-api/#api-standards

Currently the error code descriptions in the API standards section are just rendered like normal. This makes them not really stand out. In my opinion, they should either be a table or the description visually indented to make them visually a child of the error code. Because of the background color for them, that is actually currently the other way around, where the error codes are indented more than their descriptions.
Look closely at the above screenshot, then check if you saw this
"Other error codes the client might encounter are" is actually a header for a different section, not part of the description for `M_UNKNOWN`.
The old spec does this very inconsistently, but also nicely illustrates a few different options by accident:

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 with the API standards section at the linked Matrix specification page and inspect the source or rendering path that produces its error-code descriptions. Compare the current indentation with the screenshots and make the descriptions visually subordinate to their error codes; done means the section renders consistently and the separate header remains distinct.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- html
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100