wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Rewrite readme and update contributor docs

Browse source 
Incorporates https://github.com/matrix-org/matrix-doc/pull/3025/
This commit is contained in:
Travis Ralston 2021-04-05 11:36:11 -06:00 • committed by Richard van der Hoff
parent aab72c3d14
commit 52cd88f070
5 changed files with 117 additions and 176 deletions
Download patch file Download diff file Expand all files Collapse all files

40
meta/documentation_style.rst
View file

@ -8,52 +8,36 @@ in.
Format
------
Documentation is written either in github-flavored markdown or RST.
Documentation is written either in github-flavored markdown.
Sections
--------
RST support lots of different punctuation characters for underlines on sections.
Content in the specification MUST use the same characters in order for the
complete specification to be merged correctly. These characters are:
- ``=``
- ``-``
- ``~``
- ``+``
- ``^``
- \ `````
- ``@``
- ``:``
If you find yourself using ``^`` or beyond, you should rethink your document
layout if possible.
Markdown supports headings through the `#` prefix on text. Please avoid heavily
nested titles (h6, or 6 `#` characters) and instead re-evaluate the document structure.
Correct capitalisation for long section names
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Headings should start with a capital letter, and use lower-case otherwise.
Headings should start with a capital letter, and use lower-case otherwise. This
document is an example of what we mean.
TODOs
-----
Any RST file in this repository may make it onto ``matrix.org``. We do not want
``TODO`` markers visible there. For internal comments, notes, TODOs, use standard
RST comments like so::
.. TODO-Bob
There is something to do here. This will not be rendered by something like
rst2html.py so it is safe to put internal comments here.
You SHOULD put your username with the TODO so we know who to ask about it.
Any file in this repository might make it onto the matrix.org site, and as such
we do not want ``TODO`` markers visible there. For internal comments, notes, TODOs,
etc please use standard markdown comments (`<!-- TODO TravisR: Fix this -->`). Please
include your name in the TODO comment so we know who to ask about it in the future.
Line widths
-----------
We use 80 characters for line widths. This is a guideline and can be flouted IF
We use 80 characters for line widths. This is a guideline and can be ignored IF
AND ONLY IF it makes reading more legible. Use common sense.
For proposals, please use 120 characters as a guide.
Stylistic notes
---------------