Skip to content

Sync public contributor guide with current internal guidance - #1191

Draft
M. Baldwin (msmbaldwin) wants to merge 2 commits into
MicrosoftDocs:mainfrom
msmbaldwin:sync-with-internal-guide
Draft

Sync public contributor guide with current internal guidance#1191
M. Baldwin (msmbaldwin) wants to merge 2 commits into
MicrosoftDocs:mainfrom
msmbaldwin:sync-with-internal-guide

Conversation

@msmbaldwin

Copy link
Copy Markdown

Summary

This PR brings the public contributor guide back in sync with the current authoritative internal guidance, and ports over a few externally-relevant topics that were missing. All changes are factual/procedural — public tone and structure are preserved. Opened as a draft for review.

Factual/procedural fixes to existing articles

Article Change
how-to-write-links.md Add FWLinks / aka.ms guidance (don't use ShortLinks in Learn content; FWLink /p/ only as external last resort).
metadata.md Add ms.topic and ms.service to the required metadata attributes (were missing).
how-to-create-github-issues.md, provide-feedback.md Update feedback control names to current UI: This page / This product.
process-pull-request.md Clarify that the merge method is repository-specific (#sign-off vs. Squash and merge), not universal.
create-pull-request.md Note the release-branch exception for the base branch; fix PR-title default wording.
how-to-write-major-edits.md Add a note about basing work on a release branch when the repo uses one instead of main.
how-to-write-docs-auth-pack.md Add Learn Scaffolding and Cleanup scripts to the bundled extensions list.
get-started-setup-tools.md Link to the new AI-assisted authoring tools article.

New articles (ported from internal guidance, made external-appropriate)

  • Contributor License Agreement (contributor-license-agreement.md) — the CLA flow for community contributors, incl. the @microsoft-github-policy-service bot commands.
  • Accessibility and alt text (accessibility.md) — meaningful alt text, accessible tables/links, and build validation.
  • Add images and screenshots (add-images.md) — image syntax, storage/naming, compression, alt text, and secure screenshots (scrub PII).
  • AI-assisted authoring tools (ai-authoring-tools.md) — optional Learn Authoring Assistant and GitHub Copilot, alongside the Learn Authoring Pack.

TOC.yml updated for the new articles; ms.date refreshed on edited files.

Notes for reviewers

  • Content was cross-checked against the internal guide; a few originally-suspected divergences were verified as already-correct in the public guide and intentionally left unchanged (e.g., the inline-HTML rule and dev_langs coverage).
  • The new articles avoid internal-only tooling and don't require anything a public contributor can't do.

Factual/procedural updates aligning the public contributor guide with the
authoritative internal guide (docs-help-pr):

- Links: add FWLinks/aka.ms guidance (don't use in Learn content).
- Metadata: add ms.topic and ms.service to required attributes.
- GitHub issues & feedback: update feedback control names to
  "This page" / "This product".
- Process a pull request: merge method is repository-specific
  (#sign-off vs. Squash and merge).
- Create a pull request / Make major changes: note the release-branch
  exception when the base branch isn't main; fix PR-title default wording.
- Learn Authoring Pack: add Learn Scaffolding and Cleanup scripts to the
  bundled extensions.
- Install content-authoring tools: link to new AI-assisted authoring tools.

New articles ported from internal guidance (external-appropriate):
- Contributor License Agreement (CLA) flow for community contributors.
- Accessibility and alt text.
- Add images and screenshots (incl. secure screenshots).
- AI-assisted authoring tools (Learn Authoring Assistant, GitHub Copilot).

TOC updated for the new articles; ms.date refreshed on edited files.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 902b5092-7ab8-4365-8259-7dbbb99c3bc4
@learn-build-service-prod

Copy link
Copy Markdown

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

…late

- Revert the FWLinks/aka.ms section in the links article: external
  contributors can't create ShortLinks, so that guidance is internal-only
  and out of scope for the public guide. (Restores the file to its
  original state, including ms.date.)
- Fix an unintended edit to metadata.md where the required-attributes date
  bump also overwrote the Learn Article Templates dynamic placeholder
  "ms.date: {@Date}". Restored the placeholder; the auto-populate behavior
  is unchanged.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 902b5092-7ab8-4365-8259-7dbbb99c3bc4
@learn-build-service-prod

Copy link
Copy Markdown

Learn Build status updates of commit 81006a8:

⚠️ Validation status: warnings

File Status Preview URL Details
Contribute/content/accessibility.md ⚠️Warning View Details
Contribute/content/add-images.md ⚠️Warning View Details
Contribute/content/ai-authoring-tools.md ⚠️Warning View Details
Contribute/content/contributor-license-agreement.md ⚠️Warning View Details
Contribute/content/how-to-write-docs-auth-pack.md 💡Suggestion View Details
Contribute/content/metadata.md 💡Suggestion View Details
Contribute/content/create-pull-request.md ✅Succeeded View
Contribute/content/get-started-setup-tools.md ✅Succeeded View
Contribute/content/how-to-create-github-issues.md ✅Succeeded View
Contribute/content/how-to-write-major-edits.md ✅Succeeded View
Contribute/content/process-pull-request.md ✅Succeeded View
Contribute/content/provide-feedback.md ✅Succeeded View
Contribute/content/TOC.yml ✅Succeeded View

Contribute/content/accessibility.md

  • Line 4, Column 9: [Warning: author-not-found - See documentation] Invalid value for author: 'cahublou' is not a valid GitHub ID.

Contribute/content/add-images.md

  • Line 4, Column 9: [Warning: author-not-found - See documentation] Invalid value for author: 'cahublou' is not a valid GitHub ID.

Contribute/content/ai-authoring-tools.md

  • Line 7, Column 9: [Warning: author-not-found - See documentation] Invalid value for author: 'cahublou' is not a valid GitHub ID.

Contribute/content/contributor-license-agreement.md

  • Line 4, Column 9: [Warning: author-not-found - See documentation] Invalid value for author: 'cahublou' is not a valid GitHub ID.

Contribute/content/how-to-write-docs-auth-pack.md

  • Line 8, Column 12: [Suggestion: ms-author-invalid - See documentation] Invalid value for 'ms.author', 'mbradley' is not a valid Microsoft alias.

Contribute/content/metadata.md

  • Line 5, Column 12: [Suggestion: ms-author-invalid - See documentation] Invalid value for 'ms.author', 'sabarret' is not a valid Microsoft alias.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant