Browse Source

Add XML docs contribution guidelines

Update guidelines
pull/1304/head
Still Hsu 6 years ago
parent
commit
70a199530a
1 changed files with 35 additions and 10 deletions
  1. +35
    -10
      docs/CONTRIBUTING.md

+ 35
- 10
docs/CONTRIBUTING.md View File

@@ -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)

Loading…
Cancel
Save