The Orleans documentation is built in Markdown. We use a few simple conventions to ensure a homogeneous style throughout the full set of documents.
These standards are being introduced. If you have issues with these guidelines then raise an issue or a Pull Request. If you find documentation that fails to meet the guidelines, then make a fix and submit a pull request. Also if you are using windows 10 you can go to the store and find free MarkDown editors like this
The documentation will follow US-English spelling. Desktop tools like http://markdownpad.com have spell checking features.
Each sentence should be written on a single line, and only one sentence per line. This makes merging changes easier and also helps identify verbose language.
Paragraphs in Markdown are just one or more lines of consecutive text followed by one or more blank lines.
Heading should be used to structure a document. Avoid using other emphasis features like ALLCAPS, Italics or bold to identify a new topic. Using a header is not only more consistent, but also allows linking to the header.
At the end of a page, it is helpful to link to the next logical page in the documentation. If the page is the last in a sub-section then linking back to the index page is useful.
Blocks of example code should be formatted with the triple back tick format followed by the language
``` csharp
[StorageProvider(ProviderName="store1")]
public class MyGrain<IMyGrainState> ...
{
...
}
```
Which will render as
[StorageProvider(ProviderName="store1")]
public class MyGrain<IMyGrainState> ...
{
...
}
Inline code should be marked with a single backtick (`).
This include references to:
Task<T>gameOrleans.Storage.AzureTableStorageIf showing text that is an output (e.g. text file content or console output) you can either use the triple back tick without specifying a language or you can indent the content. For example:
1 said: Welcome to my team!
0 said: Thanks!
1 said: Thanks!
0 said: Thanks!
When referencing a filename, directory/folder or URI then use standard italics to format.
This can be done by surrounding the string with either with a single asterisk (*) or a single underscore (_)
Examples:
Markdown supports tabular data. Tables could be used to structure data so that is is easily consumable for the reader.
| Suffix | Unit |
|---|---|
| ms | millisecond(s) |
| s | second(s) |
| m | minute(s) |
When referencing another concept, the concept should be linked to. Forward and backward references with in a page can be linked to via the header. e.g. link back to Structure Links to other documents can either link to the page, or a sub-section/header within the page. External links should be exposed as a the full link e.g. https://github.com/dotnet/roslyn
The Orleans documentation is managed as Markdown files in a Git repository hosted on GitHub in the gh-pages branch.
See the GitHub Pages documentation on how to use the gh-pages branch convention for “Project site” documents.