Minor cleanup on recently ported doc pages

CHANGES.md

@@ -1,16 +1,17 @@
 UNRELEASED
 ==========
 
-We've decided to move the existing, somewhat stagnant pages from the GitHub wiki 
+We've decided to move the existing, somewhat stagnant pages from the GitHub wiki
 to the [documentation website](https://matrix-org.github.io/synapse/latest/).
+
 This was done for two reasons. The first was to ensure that changes are checked by 
 multiple authors before being committed (everyone makes mistakes!) and the second
 was visibility of the documentation. Not everyone knows that Synapse has some very
 useful information hidden away in its GitHub wiki pages. Bringing them to the 
 documentation website should help with visibility, as well as keep all Synapse documentation
 in one, easily-searchable location.
 
-Note that contributions to the documentation website happen through [GitHub pull 
+Note that contributions to the documentation website happen through [GitHub pull
 requests](https://github.com/matrix-org/synapse/pulls). Please visit [#synapse-dev:matrix.org](https://matrix.to/#/#synapse-dev:matrix.org)
 if you need help with the process!
 
@@ -102,7 +103,6 @@ Internal Changes
 - Refactor including the bundled relations when serializing an event. ([\#11408](https://github.com/matrix-org/synapse/issues/11408))
 
 
-
 Synapse 1.47.1 (2021-11-23)
 ===========================
 

changelog.d/11466.misc

@@ -0,0 +1 @@
+Update and clean up recently ported documentation pages.

docs/usage/administration/admin_faq.md

@@ -6,27 +6,31 @@ If your server already has an admin account you should use the user admin API to
 
 If you don't have any admin accounts yet you won't be able to use the admin API so you'll have to edit the database manually. Manually editing the database is generally not recommended so once you have an admin account, use the admin APIs to make further changes.
 
-    UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
-
+```sql
+UPDATE users SET admin = 1 WHERE name = '@foo:bar.com';
+```
 What servers are my server talking to?
 ---
 Run this sql query on your db:
-
-    SELECT * FROM destinations;
+```sql
+SELECT * FROM destinations;
+```
 
 What servers are currently participating in this room?
 ---
 Run this sql query on your db:
-
-    SELECT DISTINCT split_part(state_key, ':', 2)
-        FROM current_state_events AS c
-        INNER JOIN room_memberships AS m USING (room_id, event_id)
-        WHERE room_id = '!cURbafjkfsMDVwdRDQ:matrix.org' AND membership = 'join';
+```sql
+SELECT DISTINCT split_part(state_key, ':', 2)
+    FROM current_state_events AS c
+    INNER JOIN room_memberships AS m USING (room_id, event_id)
+    WHERE room_id = '!cURbafjkfsMDVwdRDQ:matrix.org' AND membership = 'join';
+```
 
 What users are registered on my server?
 ---
-
-    SELECT NAME from users;
+```sql
+SELECT NAME from users;
+```
 
 Manually resetting passwords:
 ---
@@ -50,13 +54,13 @@ There are two exceptions when it might be sensible to delete your database and s
 I've stuffed up access to my room, how can I delete it to free up the alias?
 ---
 Using the following curl command:
-
-    curl -H 'Authorization: Bearer <access-token>' -X DELETE https://matrix.org/_matrix/client/r0/directory/room/<room-alias>
-
-\<access-token\> - can be obtained in riot by looking in the riot settings, down the bottom is:
+```
+curl -H 'Authorization: Bearer <access-token>' -X DELETE https://matrix.org/_matrix/client/r0/directory/room/<room-alias>
+```
+`<access-token>` - can be obtained in riot by looking in the riot settings, down the bottom is:
 Access Token:\<click to reveal\> 
 
-\<room-alias\> - the room alias, eg. #my_room:matrix.org this possibly needs to be URL encoded also, for example  %23my_room%3Amatrix.org
+`<room-alias>` - the room alias, eg. #my_room:matrix.org this possibly needs to be URL encoded also, for example  %23my_room%3Amatrix.org
 
 How can I find the lines corresponding to a given HTTP request in my homeserver log?
 ---
@@ -93,4 +97,7 @@ WHERE g.room_id = s.room_id
 GROUP BY s.canonical_alias, g.room_id
 ORDER BY num_rows desc 
 LIMIT 10;
-```
+```
+
+You can also use the [List Room API](../../admin_api/rooms.md#list-room-api)
+and `order_by` `state_events`.

docs/usage/administration/database_maintenance_tools.md

@@ -5,32 +5,14 @@ This blog post by Victor Berger explains how to use many of the tools listed on
 ## [Purge Remote Media API](../../admin_api/media_admin_api.md#purge-remote-media-api)
 The purge remote media API allows server admins to purge old cached remote media.
 
-#### Purge local media 
-
-There is no purge API for local media because you may be the only one with a copy. If you are sure you want to delete local media you could use something like the following to delete media that hasn't been accessed in a while.
-
-```
-find /path/to/synapse/media_store/local_content -atime +365 -delete
-find /path/to/synapse/media_store/local_thumbnails -atime +365 -delete
-```
-
-This will delete media that hasn't been accessed in 365 days.
-
-**Warning, check noatime flag**: You also have to double-check that the filesystem where synapse's media store don't have [noatime flag](https://unix.stackexchange.com/questions/219015/how-to-disable-access-time-settings-in-debian-linux/219017#219017). Check it with `mount`, `noatime` is something that is usually enabled by default to reduce read-write operations in the filesystem for a feature is not so demanded.
+## [Purge Local Media API](../../admin_api/media_admin_api.md#delete-local-media)
+This API deletes the *local* media from the disk of your own server.
 
 ## [Purge History API](../../admin_api/purge_history_api.md)
 The purge history API allows server admins to purge historic events from their database, reclaiming disk space.
 
-## [synapse_janitor.sql](https://github.com/xwiki-labs/synapse_scripts)
-
-- this project is [unmantained and dangerous](https://github.com/xwiki-labs/synapse_scripts#unmaintained-and-dangerous)
-- USE WITH CAUTION. It may cause database corruption (see https://github.com/matrix-org/synapse/issues/7305 for example).
-- ["Our team hasn't used any of these scripts for some time (possibly years) (...) if anyone wants to volunteer to maintain this repo I'd be happy to transfer ownership.](https://github.com/xwiki-labs/synapse_scripts/pull/12#issuecomment-617275345) 
-
-Cleans a synapse Postgres database of deleted messages and abandoned rooms.
-
 ## [synapse-compress-state](https://github.com/matrix-org/rust-synapse-compress-state)
 Tool for compressing (deduplicating) `state_groups_state` table.
 
-## [SQL for analyzing Synapse PostgreSQL database stats](https://github.com/matrix-org/synapse/wiki/SQL-for-analyzing-Synapse-PostgreSQL-database-stats)
-Some easy SQL that reports useful stat about Matrix Synapse database.
+## [SQL for analyzing Synapse PostgreSQL database stats](useful_sql_for_admins.md)
+Some easy SQL that reports useful stats about your Synapse database.

docs/usage/administration/understanding_synapse_through_grafana_graphs.md

@@ -1,6 +1,12 @@
 ## Understanding Synapse through Grafana graphs
 
-It is possible monitor much of the internal state of Synapse using [Prometheus](https://prometheus.io) metrics and [Grafana](https://grafana.com/). A guide for configuring Synapse to provide metrics is available [here](../../metrics-howto.md) and information on setting up Grafana is [here](https://github.com/matrix-org/synapse/tree/master/contrib/grafana). In this setup, Prometheus will periodically scrape the information Synapse provides and store a record of it over time. Grafana is then used as an interface to query and present this information through a series of pretty graphs.
+It is possible to monitor much of the internal state of Synapse using [Prometheus](https://prometheus.io) 
+metrics and [Grafana](https://grafana.com/). 
+A guide for configuring Synapse to provide metrics is available [here](../../metrics-howto.md) 
+and information on setting up Grafana is [here](https://github.com/matrix-org/synapse/tree/master/contrib/grafana).
+In this setup, Prometheus will periodically scrape the information Synapse provides and
+store a record of it over time. Grafana is then used as an interface to query and
+present this information through a series of pretty graphs.
 
 Once you have grafana set up, and assuming you're using [our grafana dashboard template](https://github.com/matrix-org/synapse/blob/master/contrib/grafana/synapse.json), look for the following graphs when debugging a slow/overloaded Synapse:
 
@@ -57,16 +63,22 @@ we should probably consider raising the size of that cache by raising its cache
 
 ![image](https://user-images.githubusercontent.com/1342360/82241440-13566680-9934-11ea-8b88-ba468db937ed.png)
 
-Forward extremities are the leaf events at the end of a DAG in a room, aka events that have no children. The more exist in a room, the more [state resolution](https://matrix.org/docs/spec/server_server/r0.1.3#room-state-resolution) that Synapse needs to perform (hint: it's an expensive operation). While Synapse has code to prevent too many of these existing at one time in a room, bugs can sometimes make them crop up again.
+Forward extremities are the leaf events at the end of a DAG in a room, aka events that have no children. The more that exist in a room, the more [state resolution](https://spec.matrix.org/v1.1/server-server-api/#room-state-resolution) that Synapse needs to perform (hint: it's an expensive operation). While Synapse has code to prevent too many of these existing at one time in a room, bugs can sometimes make them crop up again.
 
 If a room has >10 forward extremities, it's worth checking which room is the culprit and potentially removing them using the SQL queries mentioned in [#1760](https://github.com/matrix-org/synapse/issues/1760).
 
 ## Garbage Collection
 
 ![image](https://user-images.githubusercontent.com/1342360/82241911-da6ac180-9934-11ea-9a0d-a311fe22acd0.png)
 
-Large spikes in garbage collection times (bigger than shown here, I'm talking in the multiple seconds range), can cause lots of problems in Synapse performance. It's more an indicator of problems, and a symptom of other problems though, so check other graphs for what might be causing it.
+Large spikes in garbage collection times (bigger than shown here, I'm talking in the 
+multiple seconds range), can cause lots of problems in Synapse performance. It's more an 
+indicator of problems, and a symptom of other problems though, so check other graphs for what might be causing it.
 
 ## Final Thoughts
 
-If you're still having performance problems with your Synapse instance and you've tried everything you can, it may just be a lack of system resources. Consider adding more CPU and RAM, and make use of [worker mode](../../workers.md) to make use of multiple CPU cores / multiple machines for your homeserver.
+If you're still having performance problems with your Synapse instance and you've 
+tried everything you can, it may just be a lack of system resources. Consider adding
+more CPU and RAM, and make use of [worker mode](../../workers.md) 
+to make use of multiple CPU cores / multiple machines for your homeserver.
+