Skip to content

1. Microsoft Teams contributor guide

Jump to bottom
Surbhi-MSFT edited this page Jan 12, 2021 · 7 revisions
guidelines image

Teams documentation is part of the Microsoft Docs technical documentation library. The content is organized into groups called docsets, each representing a group of related documents managed as a single entity. Articles in the same docset have the same URL path extension after docs.microsoft.com. For example, /docs.microsoft.com/microsoftteams/... is the beginning of the Teams docset file path. Teams articles are written in MarkDown syntax and hosted on GitHub.

Set up your workspace

✔ Install Git.

✔ Install Visual Studio Code (VS Code).

✔ Install Docs Authoring Pack directly from the VS Code Marketplace


   or

✔ Install from within VS Code:

  1. Select the Extensions icon on the side activity bar or use the View > Extensions command (Ctrl+Shift+X) and search for Docs Authoring Pack (Microsoft).

  2. Select Install.

    After the installation is complete, the Install button changes to the Manage gear button.

Review the Microsoft Docs Contributors guide

The contributors guide offers direction for creating, publishing, and updating technical content on the Microsoft Docs platform. See also, Docs style and voice quick start .

Microsoft Writing, Style, and Content guides

  • Microsoft Writing Style Guide. Consider adding this online guide to your browser's Favorites menu. It is a comprehensive resource for today's technical writing and reflects Microsoft's modern approach to voice and style.

  • Writing developer content. Teams-specific content is aimed at a developer audience with a fundamental understanding of programming concepts and processes. It is important that you provide clear, technically-accurate information in a compelling manner while maintaining Microsoft's tone and style.

  • Writing step-by-step instructions. Applied and interactive experiences are a great way for developers to learn about Microsoft products and technologies. Presenting complex or simple procedures in a progressive format is natural and user-friendly.

MarkDown reference

Microsoft Docs pages are written in MarkDown syntax and parsed through a Markdig engine. Please see Docs Markdown reference for specific tags and formatting conventions.

File Paths

Setting a valid file path for hyperlinks in your documentation can be a challenge, especially when using relative paths and creating links to other docsets. Your build won't succeed on GitHub if the file path is incorrect or invalid.

For more information on hyperlinks and file paths, see Use links in documentation.

IMPORTANT To reference an article that is part of the Teams platform docset:
 ✔ Use a relative path without a leading forward slash.
 ✔ Include the Markdown file extension.
Ex: parent directory/directory/path-to-article.md —> [Building an app for Microsoft Teams](../concepts/building-an-app.md)

To reference a Microsoft Docs library article that is not part of the Teams platform docset:
 ✔ Use a relative path that begins with a forward slash.
 ✔ Don't include the file extension.
Ex: /docset/address-to-file-location —> [Use the Microsoft Graph API to work with Microsoft Teams](/graph/api/resources/teams-api-overview)

To reference a page outside of the Microsoft Docs library, such as GitHub, use the full https file path.

Code Samples and Snippets

Code samples play an important role in helping developers successfully use APIs and SDKs. Well-presented code samples can communicate how things work more clearly than descriptive text and instructional information alone. Your code samples should be accurate, concise, well-documented, and, most importantly, reader-friendly. Code that is easy-to-read is also easy to understand, test, debug, maintain, modify, and extend. See How to include code in docs. For readability tips, see Cutting Edge : Source Code Readability Tips.

Clone this wiki locally