Update documentation style & fix room version heading order (#3683)

* Update documentation style & fix room version heading order

Also add a missing signing key section to v6.

This additionally contains various edits to the fragments to have them make a little bit more sense in context.

Finally, this updates various aspects of the documentation style which haven't previously been considered - they're added here considering we're in the area.

* changelog

* enhanced changelogs

* Minor wording adjustments

* Apply suggestions from code review

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>

content/rooms/fragments/v3-handling-redactions.md

@@ -5,7 +5,7 @@ toc_hide: true
 {{% added-in this=true %}} In room versions 1 and 2, redactions were
 explicitly part of the [authorization rules](/rooms/v1/#authorization-rules)
 under Rule 11. As of room version 3, these conditions no longer exist as
-represented by the above rules.
+represented by [this version's authorization rules](#authorization-rules).
 
 While redactions are always accepted by the authorization rules for
 events, they should not be sent to clients until both the redaction

content/rooms/fragments/v4-event-ids.md

@@ -10,5 +10,5 @@ Base64](/appendices#unpadded-base64) which replaces the 62nd and
 matches [RFC4648's definition of URL-safe
 base64](https://tools.ietf.org/html/rfc4648#section-5).
 
-Event IDs are still prefixed with `$` and may result in looking like
+Event IDs are still prefixed with `$` and might result in looking like
 `$Rqnc-F-dvnEYJTyHq_iKxU2bZ1CI92-kuZq3a5lr5Zg`.

content/rooms/v1.md

@@ -38,6 +38,20 @@ should be aware that restrictions should be generally relaxed and that
 inconsistencies may occur.
 {{% /boxes/warning %}}
 
+### Redactions
+
+[See above](#redactions).
+
+### Event format
+
+Events in version 1 rooms have the following structure:
+
+{{% definition path="api/server-server/definitions/pdu" %}}
+
+### Authorization rules
+
+{{% rver-fragment name="v1-auth-rules" %}}
+
 ### State resolution
 
 {{% boxes/warning %}}
@@ -97,16 +111,6 @@ A *conflict* occurs between states where those states have different
 `event_ids` for the same `(event_type, state_key)`. The events thus
 affected are said to be *conflicting* events.
 
-### Authorization rules
-
-{{% rver-fragment name="v1-auth-rules" %}}
-
-### Event format
-
-Events in version 1 rooms have the following structure:
-
-{{% definition path="api/server-server/definitions/pdu" %}}
-
 ### Canonical JSON
 
 {{% rver-fragment name="v1-canonical-json" %}}

content/rooms/v2.md

@@ -36,9 +36,9 @@ changing only the state resolution algorithm.
 The following sections have not been modified since v1, but are included for
 completeness.
 
-### Authorization rules
+### Redactions
 
-{{% rver-fragment name="v1-auth-rules" %}}
+{{% rver-fragment name="v1-redactions" %}}
 
 ### Event format
 
@@ -46,10 +46,10 @@ Events in rooms of this version have the following structure:
 
 {{% definition path="api/server-server/definitions/pdu" %}}
 
+### Authorization rules
+
+{{% rver-fragment name="v1-auth-rules" %}}
+
 ### Canonical JSON
 
 {{% rver-fragment name="v1-canonical-json" %}}
-
-### Redactions
-
-{{% rver-fragment name="v1-redactions" %}}

content/rooms/v3.md

@@ -37,6 +37,11 @@ use cases should reference.
 Room version 3 uses the event format described here in addition to
 all the remaining behaviour described by [room version 2](/rooms/v2).
 
+### Handling redactions
+
+<!-- set withVersioning=true so we get all the "new in this version" stuff -->
+{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}}
+
 ### Event IDs
 
 {{% boxes/rationale %}}
@@ -76,8 +81,7 @@ The complete structure of a event in a v3 room is shown below.
 
 {{% definition path="api/server-server/definitions/pdu_v3" %}}
 
-
-### Authorization rules for events
+### Authorization rules
 
 {{% added-in this=true %}} `m.room.redaction` events are no longer
 explicitly part of the auth rules. They are still subject to the
@@ -89,16 +93,15 @@ section below for more information.
 <!-- set withVersioning=true so we get all the "new in this version" stuff -->
 {{% rver-fragment name="v3-auth-rules" withVersioning=true %}}
 
-### Handling redactions
-
-<!-- set withVersioning=true so we get all the "new in this version" stuff -->
-{{% rver-fragment name="v3-handling-redactions" withVersioning=true %}}
-
 ## Unchanged from v2
 
 The following sections have not been modified since v2, but are included for
 completeness.
 
+### Redactions
+
+{{% rver-fragment name="v1-redactions" %}}
+
 ### State resolution
 
 {{% rver-fragment name="v2-state-res" %}}
@@ -106,7 +109,3 @@ completeness.
 ### Canonical JSON
 
 {{% rver-fragment name="v1-canonical-json" %}}
-
-### Redactions
-
-{{% rver-fragment name="v1-redactions" %}}

content/rooms/v4.md

@@ -53,26 +53,14 @@ generally made administration harder.
 The following sections have not been modified since v3, but are included for
 completeness.
 
-### State resolution
+### Redactions
 
-{{% rver-fragment name="v2-state-res" %}}
-
-### Authorization rules
-
-{{% rver-fragment name="v3-auth-rules" %}}
+{{% rver-fragment name="v1-redactions" %}}
 
 ### Handling redactions
 
 {{% rver-fragment name="v3-handling-redactions" %}}
 
-### Canonical JSON
-
-{{% rver-fragment name="v1-canonical-json" %}}
-
-### Redactions
-
-{{% rver-fragment name="v1-redactions" %}}
-
 ### Event format
 
 The event format is the same as [room version 3](/rooms/v3#event-format),
@@ -80,3 +68,15 @@ however the event IDs in the following example are updated to reflect
 the changes in this room version.
 
 {{% rver-fragment name="v4-event-format" %}}
+
+### Authorization rules
+
+{{% rver-fragment name="v3-auth-rules" %}}
+
+### State resolution
+
+{{% rver-fragment name="v2-state-res" %}}
+
+### Canonical JSON
+
+{{% rver-fragment name="v1-canonical-json" %}}

content/rooms/v5.md

@@ -35,13 +35,9 @@ Room version 5 uses the same algorithms defined in [room version
 The following sections have not been modified since v4, but are included for
 completeness.
 
-### State resolution
+### Redactions
 
-{{% rver-fragment name="v2-state-res" %}}
-
-### Authorization rules
-
-{{% rver-fragment name="v3-auth-rules" %}}
+{{% rver-fragment name="v1-redactions" %}}
 
 ### Handling redactions
 
@@ -55,10 +51,14 @@ completeness.
 
 {{% rver-fragment name="v4-event-format" %}}
 
+### Authorization rules
+
+{{% rver-fragment name="v3-auth-rules" %}}
+
+### State resolution
+
+{{% rver-fragment name="v2-state-res" %}}
+
 ### Canonical JSON
 
 {{% rver-fragment name="v1-canonical-json" %}}
-
-### Redactions
-
-{{% rver-fragment name="v1-redactions" %}}

content/rooms/v6.md

@@ -38,7 +38,7 @@ in [room version 5](/rooms/v5).
 
 [See above](#redactions).
 
-### Authorization rules for events
+### Authorization rules
 
 `m.room.redaction` events are not explicitly part of the auth rules.
 They are still subject to the minimum power level rules, but should always
@@ -200,9 +200,9 @@ Some consequences of these rules:
 The following sections have not been modified since v5, but are included for
 completeness.
 
-### State resolution
+### Handling redactions
 
-{{% rver-fragment name="v2-state-res" %}}
+{{% rver-fragment name="v3-handling-redactions" %}}
 
 ### Event IDs
 
@@ -212,6 +212,10 @@ completeness.
 
 {{% rver-fragment name="v4-event-format" %}}
 
-### Handling redactions
+### State resolution
 
-{{% rver-fragment name="v3-handling-redactions" %}}
+{{% rver-fragment name="v2-state-res" %}}
+
+### Signing key validity period
+
+{{% rver-fragment name="v5-signing-requirements" %}}

content/rooms/v7.md

@@ -188,9 +188,13 @@ Some consequences of these rules:
 The following sections have not been modified since v6, but are included for
 completeness.
 
-### State resolution
+### Redactions
 
-{{% rver-fragment name="v2-state-res" %}}
+{{% rver-fragment name="v6-redactions" %}}
+
+### Handling redactions
+
+{{% rver-fragment name="v3-handling-redactions" %}}
 
 ### Event IDs
 
@@ -200,9 +204,9 @@ completeness.
 
 {{% rver-fragment name="v4-event-format" %}}
 
-### Handling redactions
+### State resolution
 
-{{% rver-fragment name="v3-handling-redactions" %}}
+{{% rver-fragment name="v2-state-res" %}}
 
 ### Canonical JSON
 
@@ -211,7 +215,3 @@ completeness.
 ### Signing key validity period
 
 {{% rver-fragment name="v5-signing-requirements" %}}
-
-### Redactions
-
-{{% rver-fragment name="v6-redactions" %}}

content/rooms/v8.md

@@ -98,9 +98,9 @@ and 4.3.5).
 The following sections have not been modified since v7, but are included for
 completeness.
 
-### State resolution
+### Handling redactions
 
-{{% rver-fragment name="v2-state-res" %}}
+{{% rver-fragment name="v3-handling-redactions" %}}
 
 ### Event IDs
 
@@ -110,9 +110,9 @@ completeness.
 
 {{% rver-fragment name="v4-event-format" %}}
 
-### Handling redactions
+### State resolution
 
-{{% rver-fragment name="v3-handling-redactions" %}}
+{{% rver-fragment name="v2-state-res" %}}
 
 ### Canonical JSON
 

content/rooms/v9.md

@@ -90,13 +90,9 @@ following considerations.
 The following sections have not been modified since v8, but are included for
 completeness.
 
-### State resolution
+### Handling redactions
 
-{{% rver-fragment name="v2-state-res" %}}
-
-### Authorization rules
-
-{{% rver-fragment name="v8-auth-rules" %}}
+{{% rver-fragment name="v3-handling-redactions" %}}
 
 ### Event IDs
 
@@ -106,9 +102,13 @@ completeness.
 
 {{% rver-fragment name="v4-event-format" %}}
 
-### Handling redactions
+### Authorization rules
 
-{{% rver-fragment name="v3-handling-redactions" %}}
+{{% rver-fragment name="v8-auth-rules" %}}
+
+### State resolution
+
+{{% rver-fragment name="v2-state-res" %}}
 
 ### Canonical JSON