|
|
@@ -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/ |
|
|
|
* [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) |