From 70a199530a00e715fd3ef9d1423af4ea41d15e42 Mon Sep 17 00:00:00 2001
From: Still Hsu <341464@gmail.com>
Date: Sat, 16 Feb 2019 11:52:05 +0800
Subject: [PATCH] Add XML docs contribution guidelines

Update guidelines
---
 docs/CONTRIBUTING.md | 45 ++++++++++++++++++++++++++++++++++----------
 1 file changed, 35 insertions(+), 10 deletions(-)

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
index 8641d377e..74290e595 100644
--- a/docs/CONTRIBUTING.md
+++ b/docs/CONTRIBUTING.md
@@ -1,23 +1,46 @@
 # Contributing to Docs
 
-## General Guidelines
+First of all, thank you for your interest in contributing to our
+documentation work. We really appreciate it! That being said,
+there are several guidelines you should attempt to follow when adding
+to/changing the documentation.
 
-We do not have any strict conditions for writing documentation,
-but keep these guidelines in mind:
+## General Guidelines
 
-* Keep code samples in the `guides/samples` folder
+* Keep code samples in each section's `samples` folder
 * When referencing an object in the API, link to its page in the
  API documentation
 * Documentation should be written in an FAQ/Wiki-style format
 * Documentation should be written in clear and proper English*
 
 \* If anyone is interested in translating documentation into other
-languages, please open an issue or contact me on
-Discord (`foxbot#0282`).
+languages, please open an issue or contact `foxbot#0282` on
+Discord.
+
+## XML Docstrings Guidelines
 
-## Style Consistencies
+* When using the `<summary>` tag, use concise verbs. For example:
+
+```cs
+/// <summary> Gets or sets the guild user in this object. </summary>
+public IGuildUser GuildUser { get; set; }
+```
 
-* Use a ruler set at 70 characters
+* The `<summary>` tag should not be more than 3 lines long. Consider
+simplifying the terms or using the `<remarks>` tag instead.
+* When using the `<code>` tag, put the code sample within the
+`src/Discord.Net.Examples` project under the corresponding path of
+the object and surround the code with a `#region` tag.
+* If the remarks you are looking to write are too long, consider
+writing a shorter version in the XML docs while keeping the longer
+version in the `overwrites` folder using the DocFX overwrites syntax.
+  * You may find an example of this in the samples provided within
+  the folder.
+
+## Docs Guide Guidelines
+
+* Use a ruler set at 70 characters (use the docs workspace provided
+if you are using Visual Studio Code)
 * Links should use long syntax
 * Pages should be short and concise, not broad and long
 
@@ -31,5 +54,7 @@ Please consult the [API Documentation] for more information.
 
 ## Recommended Reads
 
-* http://docs.microsoft.com
-* http://flask.pocoo.org/docs/0.12/
\ No newline at end of file
+* [Microsoft Docs](https://docs.microsoft.com)
+* [Flask Docs](https://flask.pocoo.org/docs/1.0/)
+* [DocFX Manual](https://dotnet.github.io/docfx/)
+* [Sandcastle XML Guide](http://ewsoftware.github.io/XMLCommentsGuide)
\ No newline at end of file