| @@ -1,23 +1,46 @@ | |||||
| # Contributing to Docs | # 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 | * When referencing an object in the API, link to its page in the | ||||
| API documentation | API documentation | ||||
| * Documentation should be written in an FAQ/Wiki-style format | * Documentation should be written in an FAQ/Wiki-style format | ||||
| * Documentation should be written in clear and proper English* | * Documentation should be written in clear and proper English* | ||||
| \* If anyone is interested in translating documentation into other | \* 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 | * Links should use long syntax | ||||
| * Pages should be short and concise, not broad and long | * Pages should be short and concise, not broad and long | ||||
| @@ -31,5 +54,7 @@ Please consult the [API Documentation] for more information. | |||||
| ## Recommended Reads | ## Recommended Reads | ||||
| * http://docs.microsoft.com | |||||
| * http://flask.pocoo.org/docs/0.12/ | |||||
| * [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) | |||||