matrix-org / matrix-org/matrix-spec

We should use real world examples instead of descriptions in field properties

Open
#474 0 comments 0 reactions 0 assignees View on GitHub
A-Application-Services A-Client-Server A-Identity-Service A-S2S clarification meta
Dominant language
HTML
Stars
330
Forks
150
Avg merge
2h 21m
Merged PRs (30d)
3

Description

For example, the PDU examples have `"ed25519:key_version:": "86BytesOfSignatureOfTheRedactedEvent"` which doesn't really show what the expected value could look like.

Instead, we should go through all the examples and make them match a real world example (replacing domain names with example.org). Ideally, those examples would have all or most of the possible characters present to show that things like `+` and `-` can be in some event IDs.

Contributor guide

Open the contributing guide

Research direction

Start by locating the PDU examples and the field-property examples in the Matrix specification. Replace descriptive placeholders with realistic example.org values, including representative characters such as + and -, and finish when the examples demonstrate the expected value shapes throughout the specification.

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
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.