Authoring documentation

This topic will contain information you need to know when authoring content in our system.

1. Make sure all your files and art assets are inside your docset. The current system will not be able to reference any file that is not inside the docset (e.g. other repositories). Trying to reference a file outside the docset will cause the build to fail.
2. When adding HTML comments, use the following syntax: <!-- Comments -->.
3. If a topic has not been added to a TOC, then a TOC will not be shown when the topic is rendered.
4. While we do not provide any templates out-of-the-box right now, please make sure that you abide to the common structure of existing Markdown files. Remember - this is documentation, not a blog. Contributions of a blog-like nature will be rejected.
5. When creating new documents, please follow the structure of other Visual F# documents. That means you need to follow the same section naming conventions and representations.
6. When referencing other MSDN documents through links, always use HTTPS and culture-agnostic versions of the links. For example, http://msdn.microsoft.com/en-us/library/ms191455 becomes https://msdn.microsoft.com/library/ms191455.
7. All assets (e.g. images, code snippets) should be hosted within the repo. Any external, non-Microsoft content included in any doc will result in a rejected PR.
8. We do not allow inclusion of content without proper permission from the original author. Same applies to content that is under a more restrictive license than the docs. This means that even if, for example, an image artist allows the use of a diagram, but the license is more restrictive than the content of the page, you can't add that image within the doc.
9. Short code samples can be included inline. Larger code samples need to referenced from a code file. Refer to the Code Snippets page for details.