Microsoft Learn Authoring Assistant

Microsoft Learn Authoring Assistant version 1 works with GitHub Copilot Chat to help authors improve their Learn content based on grammatical rules and Microsoft's official writing guidance. This AI-powered extension analyzes Markdown content and automatically fixes grammatical and voice issues to improve clarity and readability. You can accept the suggested edits as-is, make your own tweaks to the edited text, or ignore unhelpful suggestions and leave text as is.

The v1 release provides a simple experience for analyzing Learn Markdown files with a custom model and enforcing a set of rules from the Microsoft Writing Style Guide. The style guide helps authors write simple, straightforward technical content that customers of all backgrounds can understand and engage with. Learn Authoring Assistant brings the style guide into Learn's core authoring environment, VS Code. Using GitHub Copilot Chat, authors can ask the Assistant to suggest edits. The Assistant runs on the current article, identifies passages that don't conform with the style guide, and updates the content in a Suggested edits pane. Authors can then review the edits and tweak or revert them if necessary. The chat summarizes the edits, notes which style rules were applied, and links to the online guide for more information. Users can provide feedback on the edits to help continuously improve the model.

This release also includes a preview version of a new rule that checks product and technology names against the Microsoft corporate taxonomy to ensure accuracy and correct branding.

Note: Learn Authoring Assistant is only available to Microsoft employees.

Prerequisites

• A Microsoft employee account
• Visual Studio Code
• GitHub Copilot
• GitHub Copilot chat
• A GitHub account and Git client
• A locally cloned Learn content repository

Settings

By default, Learn Authoring Assistant only supports one command, /suggestEdits. This command runs all supported style guide rules against your current Markdown file. To also run the preview branding rule, use_correct_branding, you must first enable it via the extension settings.

1. In VS Code, select File > Preferences > Settings and then find the settings for the Microsoft Learn Authoring Assistant extension.

2. Select one or both options:

   • Enable Branding Correction: This option adds the use_correct_branding rule to the /suggestEdits command so that you get all suggestions from a single command. Choose this option if you want to preview the intended simple workflow for improving content, but be aware that the current version of the rule has many false positives.
   • Enable Branding Correction Only Mode: This option activates the /correctBranding command, which you can run separately to get suggestions from the preview use_correct_branding rule. Choose this option if you want to test the new rule without adding noise to the /suggestEdits command.

Improve content with Learn Authoring Assistant

To run the Authoring Assistant on a Learn Markdown article:

1. In VS Code, open the locally cloned repository that contains your Learn content.
2. Open or create a draft Markdown file.
3. From the VS Code View menu, select Chat.
4. In the Chat pane, enter @learn-authoring-assistant /suggestEdits or @learn-authoring-assistant /correctBranding (if activated).
5. Sign in to your Microsoft Corp account if prompted to do so.
6. Learn Authoring Assistant analyzes your file against the set of supported rules and suggests edits in a custom suggestions panel. Suggestions show as a Markdown diff. Hover over the updated text to see the review options toolbar.

To apply an edit as is:

1. Select the checkmark icon from the toolbar.
2. The checkmark icon changes to a revert icon, which you can use to revert the applied edit if you change your mind.

To customize an edit:

1. Select the pencil icon from the toolbar.
2. Make your changes in the text box that opens.
3. Select the checkmark under the text box to apply the customized text.

To reject an edit:

1. Ignore the edit. You don't have to manually reject it. There's currently no way to hide or dismiss a rejected edit, but you can select thumbs down from the toolbar to mark it as unhelpful.

To apply all edits in a file:

1. Select the Apply all button in the suggestions pane. Be sure to fully review all suggestions before you apply them.

To revert all applied edits in a file:

1. Select the Revert all button in the suggestions pane.

To regenerate edits:

1. Select Regenerate.
2. The Authoring Assistant regenerates suggestions. This is useful if you've applied customized edits and want to review the updated text.

When you're done editing the file:

1. Select Complete. This action closes out the diff window and sends data about your editing session to the Authoring Assistant telemetry store.

Known issues and limitations

The following limitations apply:

• Learn Authoring Assistant is only available to Microsoft employees.
• Only Markdown files are supported.
• Only a subset of Microsoft Writing Style Guide rules are supported. The rules were prioritized by Microsoft Learn content experts to catch the most important writing problems without overwhelming the user with feedback.
• The use_correct_branding rule is in preview and might result in false positives.

Privacy Statements

MS Data Privacy Notice for Microsoft employees.