Here's what you need to know about trademarks, versioning, and metadata for the articles in windowsserverdocs-pr repository. Article authors are responsible for making sure their articles adhere to these standards and requirements.
Don't use trademark symbols after product references in articles in the technical library. They aren't required because technet.microsoft.com, docs.microsoft.com, and other official Microsoft publishing channels include a Trademark footer link to a list of Microsoft trademarks. That link fulfills the legal requirement. For background, see guidance from CELA, under "websites" and the Microsoft Writing Style Guide Copyrights and trademarks page, under "Webpages on Microsoft.com"
Several types of versioning apply to the articles in this repo:
- Versioning that indicates the product version that an article applies to is done two ways:
- Manually on a single line in the article so it's visible as text on a published article.
- By metadata, described below.
- Source content versioning is handled through Github's history on the file.
-
Put Metadata at the top of the file, above the H1 heading.
-
Separate the block from the rest of the file contents by using only three dashes in the first and last lines of the block. Don't put any other text on those lines.
-
Put each metadata name/value pair on a separate line.
-
Use one of the following syntax patterns, depending on whether the metadata requires predefined values or accepts custom values.
--- name1: predefined-value name2: "my custom value" ---
Certain metadata is required for all files published as articles in the TechNet technical library, while other metadata is recommended but not required. In some cases, only certain values are allowed for a specific piece of metadata.
| Name | Value |
|---|---|
| title | Custom value that matches the H1 heading. Determines what shows in the browser tab. |
| description | Shows in search results and affects SEO. Include appropriate keywords but keep length to less than 160 characters. |
| author | Github alias of the primary author of the article |
| ms.author | MSFT alias of the article's author or content developer responsible for the technology area covered in the article. |
| ms.date | Date of last content update. Don't update for changes to metadata only. Use the format mm/dd/yyyy. |
| ms.prod | Identifies the Windows Server version for BI reporting, based on a predefined value. |
| ms.technology | Identifies the technology area for BI reporting, based on a predefined value |
| ms.asset | GUID that identifies the article across all locales for BI reporting. Articles migrated from earlier authoring systems already have this. For articles created in Github, use a tool such as https://guidgenerator.com/. |
Metadata that appears at the top of a published article happens when the source file has formatting errors. Some common errors are:
- Missing the triple hyphens at the first and last lines of the block, or the wrong number of hyphens.
- Metadata doesn't follow the required syntax: <name>:<single space><value>
Check your file for these and any other obvious errors, then submit a PR to publish the updated file. If you're stuck, email the PR reviewers alias: [email protected]
Metadata used in this repo is based on metadata used in Content Services & International (CSI). More info, including optional metadata, is available at http://aka.ms/skyeye/meta. For business intelligence resources, see the CSI BI team's wiki.