From 2a6b6852940c29320cc463ac347c5632e9dceab2 Mon Sep 17 00:00:00 2001
From: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com>
Date: Fri, 6 Nov 2020 11:59:22 +0000
Subject: [PATCH] Add documentation about documentation to CONTRIBUTING.md
 (#8714)

This PR adds some documentation that:

* Describes who the audience for the `docs/`, `docs/dev/` and `docs/admin/` directories are, as well as Synapse's wiki page.
* Stresses that we'd like all documentation to be down in markdown.
---
 CONTRIBUTING.md      | 18 ++++++++++++++++++
 changelog.d/8714.doc |  1 +
 2 files changed, 19 insertions(+)
 create mode 100644 changelog.d/8714.doc

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index f7bea79b0..1d7bb8f96 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -156,6 +156,24 @@ directory, you will need both a regular newsfragment *and* an entry in the
 debian changelog. (Though typically such changes should be submitted as two
 separate pull requests.)
 
+## Documentation
+
+There is a growing amount of documentation located in the [docs](docs)
+directory. This documentation is intended primarily for sysadmins running their
+own Synapse instance, as well as developers interacting externally with
+Synapse. [docs/dev](docs/dev) exists primarily to house documentation for
+Synapse developers. [docs/admin_api](docs/admin_api) houses documentation
+regarding Synapse's Admin API, which is used mostly by sysadmins and external
+service developers.
+
+New files added to both folders should be written in [Github-Flavoured
+Markdown](https://guides.github.com/features/mastering-markdown/), and attempts
+should be made to migrate existing documents to markdown where possible.
+
+Some documentation also exists in [Synapse's Github
+Wiki](https://github.com/matrix-org/synapse/wiki), although this is primarily
+contributed to by community authors.
+
 ## Sign off
 
 In order to have a concrete record that your contribution is intentional
diff --git a/changelog.d/8714.doc b/changelog.d/8714.doc
new file mode 100644
index 000000000..bda22714e
--- /dev/null
+++ b/changelog.d/8714.doc
@@ -0,0 +1 @@
+Add information regarding the various sources of, and expected contributions to, Synapse's documentation to `CONTRIBUTING.md`.
\ No newline at end of file