element-hq / element-hq/synapse

Docs spec version inconsistencies.

Open
#14,777 0 comments 0 reactions 0 assignees View on GitHub
A-Docs T-Task
Dominant language
Python
Stars
4.6k
Forks
600
Avg merge
5d 22h
Merged PRs (30d)
51

Description

This issue has been migrated from [#14777](https://github.com/matrix-org/synapse/issues/14777).

---

So in the process of making #14111 i ran into that the docs refer to diffrent versions of the spec in a somewhat inconsistent manner. Some places refer to specific spec versions and others to latest. Im not sure if there is a specific reason as to why specific places should use one or the other but im filing this issue to document this.

Its logical that the list of room versions for example targets /latest/ but the case can also be made for this in other areas. The example i currently know about in the docs is for the config option `rc_invites` under the config documentation. There might be more examples but im aware of this example as it came up when i did a find operation in the config_documentation.md file as my PR touches this file.

A search in my copy of the docs (This copy im searching is for a copy of develop that is old so might be out of date) says that this shows up in other files.

A probably complete list of files where specific spec versions are referenced.

- upgrade.md
- rooms.md
- database_schema.md
- understanding_synapse_through_grafana_graphs.md
- reporting_homeserver_usage_statistics.md
- config_documentation.md
- password_auth_provider_calllbacks.md

A list containing files that mention latest. (Overlap means the file mentions both)

- media_repository.md
- sso_mapping_providers.md
- rooms.md
- user_admin_api.md
- password_auth_provider_calllbacks.md
- config_documentation.md

And then we have in the file CHANGES-2021.md on line 1829 where we refer to the unstable spec.

This should be a somewhat complete set of all times in the docs section of this repo we mention the string `spec.matrix.org/` that i searched for. The changelog entry i personally would conclude is not related to the details of this issue.

Contributor guide

Open the contributing guide

Research direction

Search the documentation files listed in the issue for `spec.matrix.org/`, including config_documentation.md, rooms.md, upgrade.md, and the other named files. Compare references to specific versions, `/latest/`, and `unstable`; clarify the intended convention for each occurrence and record or apply the resulting documentation changes. The CHANGES-2021.md entry is noted as unrelated.

Written by the indexing model from the issue text.

Assessment

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.