matrix-org / matrix-org/matrix-spec

Store spec implementation guides in an appendix of the spec

Open
#2,420 0 comments 0 reactions 0 assignees View on GitHub

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

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.