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