4309550ca0
* Remove template in favor of official samples * Fixed a variable name copy pasta mistake line 35 was _database.GetData() instead of DBService.GetData() * Experimental theme change * Change paragraph, code, heading fonts * Widen viewport * Update DocFX.Plugins.LastModified v1.2.3 * Exclude Discord.API in docs * Add remarks for SocketReaction properties * Add examples for BaseSocketClient.Events * Add additional clarification for some methods * Move IUser and IGuildChannel examples * Clarify several guides samples with notes - Reword TypeReader comment to avoid giving the idea that the sample itself is "obsolete" - Remove CommandException logging comment regarding C#7.0 as the version is now the standard across VS2017 and up - Remove suggestion about handling result in command handler since it is now advised to use CommandExecuted instead + Add additional comment to clarify ctor for DI setup * Add/migrate code examples * Incorporate material design theme License @ https://github.com/ovasquez * Update installation and nightly guide * Fix improper indentations made obvious by the widen viewport * Fix minor grammar issues + Add installation for nightly build using dotnet CLI * Fix nav level indentation * Revise "Your First Bot" article * Merge some paragraphs to avoid clutter while keeping readability * Reword the use of command framework + Add additional warning/note about environment variable * Add additional indent level * Fix indentation text warping * Remove connections sample * Update logging sample Remove redundant part of the sample * Remove mention of RPC * Remove misleading section about commands - Remove command sample from complete snippet * Revise "Your First Bot" command paragraphs * Change wording to hint devs that additional command parser packages may be available, as more and more begin to crop up * Update themes * Add XML docs contribution guidelines Update guidelines * Update CommandExecuted remarks * Fix precondition remarks typo no one saw that ok * Fix permission sample in docfx * Fix IMessageChannel samples * Update docs/_template/light-dark-theme/styles/docfx.vendor.minify.css Co-Authored-By: Still34 <341464@gmail.com> * Update docs/_template/light-dark-theme/styles/material.css Co-Authored-By: Still34 <341464@gmail.com> * Update docs/_template/light-dark-theme/styles/material.css Co-Authored-By: Still34 <341464@gmail.com>
60 lines
2.0 KiB
Markdown
60 lines
2.0 KiB
Markdown
# Contributing to Docs
|
|
|
|
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.
|
|
|
|
## General Guidelines
|
|
|
|
* 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 `foxbot#0282` on
|
|
Discord.
|
|
|
|
## XML Docstrings Guidelines
|
|
|
|
* 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; }
|
|
```
|
|
|
|
* 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
|
|
|
|
Example of long link syntax:
|
|
|
|
```md
|
|
Please consult the [API Documentation] for more information.
|
|
|
|
[API Documentation]: xref:System.String
|
|
```
|
|
|
|
## Recommended Reads
|
|
|
|
* [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) |