add documentation draft, version 2 (#41)

* add documentation draft

* be more precise about the intended audience

* rewrap

* fix typo and grammar

* embed documentation rules in CONTRIBUTING.md

* embed documentation rules in CONTRIBUTING.md, fix

* fix introductory text in documentation rules

* update entry point to documentation

* fix modified text

* replace okay with fine

Author: wlammen

CONTRIBUTING.md

@@ -106,6 +106,46 @@ to be listed here.
 
 * Mario Carneiro (@digama0)
 
+## Documentation Rules
+
+Here are some links on how to improve documentation in general:
+
+https://www.oreilly.com/content/the-eight-rules-of-good-documentation/
+
+https://guides.lib.berkeley.edu/how-to-write-good-documentation
+
+---
+
+1. Documentation is mostly collected in the ``doc`` subfolder of metamath.  As
+    an entry point to documentation a README.TXT is kept in the main folder of
+    Metamath.  This file is pure [ASCII](https://en.wikipedia.org/wiki/ASCII)
+    encoded [plain text](https://en.wikipedia.org/wiki/Plain_text).
+    
+The following rules are strong recommendations.  We encourage to follow them as
+much as possible.  But in the end we think that some sort of documentation is
+better than no documentation, so bypassing any of them is possible if somehow
+inevitable.
+    
+2. If your documentation is simple enough to be expressed as
+    [plain text](https://en.wikipedia.org/wiki/Plain_text), we recommend to
+    rely as much as possible on [ASCII](https://en.wikipedia.org/wiki/ASCII)
+    encoding.  If you need special characters, fall back to
+    [UTF-8](https://en.wikipedia.org/wiki/UTF-8).
+
+3. If your documentation is best viewed with some formatting in effect we
+    recommend using GitHub's markdown extensions (GFM) as a format style
+    embedded in plain text.  This rich text formatting is designed to be still
+    legible in simple editors.  Its format is in detail documented
+    [here](https://github.github.com/gfm), and is an extension to the
+    widespread [Markdown](https://commonmark.org/help/) format.
+    
+4. Source code documentation within sources should follow the
+    [Doxygen](https://www.doxygen.nl/index.html) style, so documentation of
+    variables and functions can be generated automatically.  Doxygen extracts
+    marked comment blocks from C sources and creates HTML pages based upon them.
+    In addition it supports Markdown to format descriptions appropriately.  See
+    https://www.doxygen.nl/manual/docblocks.html.
+
 ## For more information
 
 For more general information, see the [README.md](README.md) file.