matrix-org / matrix-org/matrix-spec

New Spec Design: Error code descriptions should be indented

Open
#778 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

aesthetic spec-redesign
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

![Screenshot_20210304_140611](https://user-images.githubusercontent.com/16312324/109968280-672b1400-7cea-11eb-8f7d-3751fbb3e383.png)

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:

![Screenshot_20210304_140834](https://user-images.githubusercontent.com/16312324/109968583-cdb03200-7cea-11eb-8b45-1615bde230ec.png)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.