[Dev-Docs AI Improvement]: Microsoft Teams developer platform overview #13676
Conversation
Acrolinx ScorecardsWe currently enforce a minimum score of 80. Click the scorecard links for each article to review the Acrolinx feedback on grammar, spelling, punctuation, writing style, and terminology:
More info about Acrolinx Use the Acrolinx extension, or sidebar, in Visual Studio Code to check spelling, grammar, style, tone, clarity, and key terminology when you're creating or updating content. For more information, see Use the Visual Studio Code extension to run Acrolinx locally. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit ab56c3f:
|
| File | Status | Preview URL | Details |
|---|---|---|---|
| msteams-platform/overview.md | View | Details |
msteams-platform/overview.md
- Line 1, Column 1: [Warning: title-missing - See documentation]
Missing required attribute: 'title'. Add a title string to show in search engine results. - Line 1, Column 1: [Warning: ms-topic-missing - See documentation]
Missing required attribute: 'ms.topic'. - Line 12, Column 1: [Warning: hard-coded-locale - See documentation]
Link 'https://learn.microsoft.com/en-us/microsoftteams/platform/assets/images/overview/dev-persona.png' contains locale code 'en-us'. For localizability, remove 'en-us' from links to most Microsoft sites. - Line 45, Column 1: [Warning: hard-coded-locale - See documentation]
Link 'https://learn.microsoft.com/en-us/microsoftteams/platform/assets/images/agents-in-teams/path.png' contains locale code 'en-us'. For localizability, remove 'en-us' from links to most Microsoft sites. - Line 46, Column 1: [Warning: hard-coded-locale - See documentation]
Link 'https://learn.microsoft.com/en-us/microsoftteams/platform/assets/images/agents-in-teams/choose-agent.png' contains locale code 'en-us'. For localizability, remove 'en-us' from links to most Microsoft sites. - Line 47, Column 1: [Warning: hard-coded-locale - See documentation]
Link 'https://learn.microsoft.com/en-us/microsoftteams/platform/assets/images/agents-in-teams/choose-app.png' contains locale code 'en-us'. For localizability, remove 'en-us' from links to most Microsoft sites. - Line 1, Column 1: [Suggestion: ms-date-missing - See documentation]
Missing required attribute: 'ms.date'. - Line 1, Column 1: [Suggestion: description-missing - See documentation]
Missing required attribute: 'description'. - Line 12, Column 1: [Suggestion: docs-link-absolute - See documentation]
Absolute link 'https://learn.microsoft.com/en-us/microsoftteams/platform/assets/images/overview/dev-persona.png' will be broken in isolated environments. Replace with a relative link. - Line 45, Column 1: [Suggestion: docs-link-absolute - See documentation]
Absolute link 'https://learn.microsoft.com/en-us/microsoftteams/platform/assets/images/agents-in-teams/path.png' will be broken in isolated environments. Replace with a relative link. - Line 46, Column 1: [Suggestion: docs-link-absolute - See documentation]
Absolute link 'https://learn.microsoft.com/en-us/microsoftteams/platform/assets/images/agents-in-teams/choose-agent.png' will be broken in isolated environments. Replace with a relative link. - Line 47, Column 1: [Suggestion: docs-link-absolute - See documentation]
Absolute link 'https://learn.microsoft.com/en-us/microsoftteams/platform/assets/images/agents-in-teams/choose-app.png' will be broken in isolated environments. Replace with a relative link.
For more details, please refer to the build report.
Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.
There was a problem hiding this comment.
Pull request overview
This PR attempts to update the Microsoft Teams developer platform overview documentation file, but introduces several critical issues that break documentation functionality. The changes convert DocFX-specific markup to plain Markdown and add a new scenario section, but these modifications are incompatible with the documentation build system.
Key changes:
- Removed YAML frontmatter metadata
- Converted DocFX image syntax to hardcoded absolute URLs
- Removed DocFX layout structures and navigation elements
- Added a new "Scenario" section at the end
| --- | ||
|
|
||
| **Scenario:** | ||
|
|
||
| Imagine you are a developer at a mid-sized company looking to enhance internal communication and streamline workflows. Your team is considering building a custom agent on the Microsoft Teams platform to automate routine tasks such as scheduling meetings, managing project timelines, and handling employee inquiries. You aim to leverage the platform's integration capabilities with Microsoft 365 to ensure seamless data flow and improve productivity across departments. |
There was a problem hiding this comment.
A new "Scenario" section has been added at the end of the document. This content appears to be example/placeholder content rather than production documentation. If this is intentional documentation content, it should be properly formatted with appropriate heading levels and integrated into the document structure. If this is placeholder or test content, it should be removed before merging.
| --- | |
| **Scenario:** | |
| Imagine you are a developer at a mid-sized company looking to enhance internal communication and streamline workflows. Your team is considering building a custom agent on the Microsoft Teams platform to automate routine tasks such as scheduling meetings, managing project timelines, and handling employee inquiries. You aim to leverage the platform's integration capabilities with Microsoft 365 to ensure seamless data flow and improve productivity across departments. | |
| --- |
| ms.localizationpriority: high | ||
| ms.date: 04/18/2025 | ||
| --- | ||
| # Microsoft Teams developer platform overview |
There was a problem hiding this comment.
The YAML frontmatter metadata has been completely removed. This metadata is required for documentation files in this repository and is used by the documentation system. The frontmatter should include fields like title, description, ms.topic, ms.localizationpriority, and ms.date as seen in other documentation files in the repository.
| Take a look at these example developer personas and agent or app scenarios: | ||
|
|
||
| :::image type="content" border="false" source="assets/images/overview/dev-persona.png" alt-text="Screenshot shows you the developer persona and user stories." lightbox="assets/images/overview/dev-persona.png"::: | ||
|  |
There was a problem hiding this comment.
The image syntax has been changed from DocFX-specific syntax to hardcoded absolute URLs. This breaks the documentation build system's ability to properly resolve images and creates maintenance issues. The original DocFX syntax :::image type="content" border="false" source="assets/images/overview/dev-persona.png" alt-text="..." lightbox="..."::: should be retained as it provides proper image handling, lightbox functionality, and relative path resolution.
|  | |
| :::image type="content" border="false" source="assets/images/overview/dev-persona.png" alt-text="Screenshot shows you the developer persona and user stories." lightbox="assets/images/overview/dev-persona.png"::: |
|  | ||
|  |
There was a problem hiding this comment.
The DocFX row/column layout structure has been removed and replaced with plain Markdown image links using absolute URLs. This breaks the intended side-by-side layout of the "choose agent" and "choose app" images, and removes the interactive links to agents-in-teams/overview.md and get-started/get-started-overview.md. The original DocFX syntax should be retained to preserve the interactive layout and navigation functionality.
|  | |
|  | |
| :::row | |
| :::column | |
| [](agents-in-teams/overview.md) | |
| ::: | |
| :::column | |
| [](get-started/get-started-overview.md) | |
| ::: | |
| ::: |
| ## Next steps | ||
|
|
||
| > [!div class="nextstepaction"] | ||
| > |
There was a problem hiding this comment.
The DocFX directive [!div class="nextstepaction"] has been removed, leaving only empty blockquote markers (>). This breaks the "Next steps" button styling and formatting. The original directive should be retained to ensure proper rendering of the next steps navigation buttons.
| > | |
| [!div class="nextstepaction"] |
This PR updates the content of the file: msteams-platform/overview.md.
Submitted by: @yashy797