├── .gitattributes ├── .github ├── PULL_REQUEST_TEMPLATE.md └── workflows │ └── check-build-warnings.yml ├── .gitignore ├── .openpublishing.publish.config.json ├── .openpublishing.redirection.json ├── .vscode ├── extensions.json └── settings.json ├── CODEOWNERS ├── Contribute ├── breadcrumb │ └── toc.yml ├── content │ ├── TOC.yml │ ├── architecture-center │ │ └── aac-contribute.md │ ├── code-in-docs.md │ ├── collections.md │ ├── create-pull-request.md │ ├── docs-authoring │ │ ├── dev-lang-completion.md │ │ ├── image-compression.md │ │ ├── includes │ │ │ ├── image-extension.md │ │ │ └── markdown-extension.md │ │ ├── jupyter-notebooks.md │ │ ├── media │ │ │ ├── compress-image.gif │ │ │ ├── configure-image-compression.png │ │ │ ├── dev-lang-completion.gif │ │ │ ├── globe-icon.png │ │ │ ├── insertnotebook.gif │ │ │ ├── json-icon.png │ │ │ ├── markdown-icon.png │ │ │ ├── metadata-explorer.png │ │ │ ├── metadata-hover.png │ │ │ ├── reformat-table-menu.png │ │ │ ├── reformat-table.gif │ │ │ ├── replace-smart-quotes.gif │ │ │ ├── show-gauntlet-bar.png │ │ │ ├── sort-redirect.gif │ │ │ ├── sort-selection-menu.png │ │ │ ├── sort-selection.gif │ │ │ ├── update-metadata-menu.png │ │ │ ├── update-metadata.gif │ │ │ └── warning-icon.png │ │ ├── metadata-explorer.md │ │ ├── metadata-updates.md │ │ ├── reformat-table.md │ │ ├── smart-quote-replacement.md │ │ ├── sort-redirects.md │ │ └── sort-selection.md │ ├── dotnet │ │ ├── api-documentation.md │ │ ├── dotnet-contribute-code-analysis.md │ │ ├── dotnet-contribute.md │ │ ├── dotnet-pr-review.md │ │ ├── dotnet-style-guide.md │ │ ├── dotnet-voice-tone.md │ │ ├── labels-projects.md │ │ ├── media │ │ │ └── labels-projects │ │ │ │ ├── release.png │ │ │ │ └── technology.png │ │ └── net-core-5-naming.md │ ├── get-started-setup-local.md │ ├── get-started-setup-tools.md │ ├── git-github-fundamentals.md │ ├── hacktoberfest.md │ ├── how-to-create-github-issues.md │ ├── how-to-review-pull-request.md │ ├── how-to-write-docs-auth-pack.md │ ├── how-to-write-links.md │ ├── how-to-write-major-edits.md │ ├── how-to-write-overview.md │ ├── how-to-write-quick-edits.md │ ├── index.md │ ├── markdown-reference.md │ ├── media │ │ ├── alerts-rendering.png │ │ ├── code-in-docs │ │ │ └── highlighted-code.png │ │ ├── collections │ │ │ ├── add-section.png │ │ │ ├── add-to-collection.png │ │ │ ├── copy-collection.png │ │ │ ├── create-article.png │ │ │ ├── create-code-samples.png │ │ │ ├── create-collection.png │ │ │ ├── create-from-item.png │ │ │ ├── create-module.png │ │ │ ├── delete-collection.png │ │ │ ├── profile.png │ │ │ └── share-collection.png │ │ ├── create-pull-request │ │ │ ├── comparing-changes.png │ │ │ └── create-pr-compare.png │ │ ├── documents │ │ │ └── markdown-cheatsheet.pdf │ │ ├── get-started-setup-local │ │ │ ├── code-drop-down.png │ │ │ ├── create-a-new-fork.png │ │ │ ├── fork.png │ │ │ ├── forked-repo.png │ │ │ ├── git-and-github-initial-setup.png │ │ │ ├── gitbash-start.png │ │ │ ├── github-2fa.png │ │ │ ├── github-login.png │ │ │ ├── pencil-icon.png │ │ │ └── repo-name.png │ │ ├── hacktoberfest │ │ │ └── github-topic.png │ │ ├── how-to-create-github-issues │ │ │ ├── comment-issue.png │ │ │ ├── feedback-links.png │ │ │ ├── github-issue.png │ │ │ └── pr-open-issue.png │ │ ├── how-to-review-pull-request │ │ │ ├── comment-box.png │ │ │ ├── compare-docs.png │ │ │ ├── find-repo-name.png │ │ │ ├── github_comment_07_review-submit.png │ │ │ ├── insert-suggestion.png │ │ │ ├── list-of-PRs.png │ │ │ ├── plus-sign.png │ │ │ ├── pr-menu.png │ │ │ └── suggestion-text.png │ │ ├── how-to-write-links │ │ │ ├── bookmark-link.png │ │ │ └── ms-assetid.png │ │ ├── how-to-write-major-edits │ │ │ ├── commit-changes.png │ │ │ ├── select-source-control.png │ │ │ ├── sync-changes.png │ │ │ └── vscode-branch.png │ │ ├── how-to-write-overview │ │ │ └── process-diagram.png │ │ ├── how-to-write-quick-edits │ │ │ ├── commit-changes.png │ │ │ ├── create-pull-request.png │ │ │ ├── edit-article.png │ │ │ └── edit-icon.png │ │ ├── markdown-reference │ │ │ ├── document.png │ │ │ └── long-description.png │ │ └── provide-feedback │ │ │ ├── feedback-box.png │ │ │ ├── feedback-link-training.png │ │ │ ├── feedback-link.png │ │ │ ├── history.png │ │ │ └── open-source.png │ ├── metadata.md │ ├── powershell-overview.md │ ├── process-pull-request.md │ ├── provide-feedback.md │ ├── qna-overview.md │ ├── seo-reference.md │ ├── style-quick-start.md │ └── text-formatting-guidelines.md ├── docfx.json ├── includes │ └── note-docsitelocfeedback.md ├── index.yml ├── media │ ├── community-perspectives-icon.png │ ├── contributor-home-hero-dark.png │ ├── contributor-home-hero-light.png │ ├── digital-swag-icon.png │ ├── emad-al-mousa.png │ ├── get-started.png │ ├── john-aziz.png │ ├── kristina-devochko.png │ ├── learning-rooms-icon.png │ ├── microsoft-qa-icon.png │ ├── shows-icon.png │ ├── tech-community-icon.png │ ├── video-discoverability.png │ ├── video-icon.png │ ├── video-meta-skills.png │ ├── video-technical-writing.png │ └── virtual-training-days-icon.png └── zone-pivot-groups.yml ├── LICENSE ├── LICENSE-CODE ├── README.md ├── SECURITY.md ├── ThirdPartyNotices.md └── ai-navigator ├── TOC.yml ├── breadcrumb └── toc.yml ├── docfx.json └── index.yml /.gitattributes: -------------------------------------------------------------------------------- 1 | # Set the default behavior, in case people don't have core.autocrlf set. 2 | * text=auto 3 | 4 | # Explicitly declare text files you want to always be normalized and converted 5 | # to native line endings on checkout. 6 | *.c text 7 | *.h text 8 | 9 | # Declare files that will always have CRLF line endings on checkout. 10 | *.sln text eol=crlf 11 | 12 | # Denote all files that are truly binary and should not be modified. 13 | *.png binary 14 | *.jpg binary -------------------------------------------------------------------------------- /.github/PULL_REQUEST_TEMPLATE.md: -------------------------------------------------------------------------------- 1 | # Contributor guide pull request 2 | 3 | Thanks for contributing to the [Microsoft Learn contributor guide](https://learn.microsoft.com/contribute/?branch=main). Please read these instructions for processing your pull request (PR). Once you've read this text, delete it and write a brief description of the changes you're proposing. 4 | 5 | ## Quality control 6 | 7 | - [ ] 1. **Successful build with no warnings or errors**: Review the build status to make sure **all checks are green** (Succeeded). 8 | 9 | - [ ] 2. **#Sign-off**: Once the PR is finalized and ready to be merged, indicate so by typing `#sign-off` in a new comment in the PR. Signing off means the document is ready for review and can be published at any time. 10 | 11 | ## Merge and publish 12 | 13 | - All PRs to this repository are manually reviewed and merged. 14 | - Once all feedback on the PR is addressed, we'll merge the PR into the main branch. 15 | 16 | ## Need help? 17 | 18 | If you have an open PR, tag the PR reviewers in a comment with your question: `@mikekinsman, @jehchow` 19 | -------------------------------------------------------------------------------- /.github/workflows/check-build-warnings.yml: -------------------------------------------------------------------------------- 1 | name: 'Status checker' 2 | 3 | on: 4 | pull_request_target: 5 | types: [opened, synchronize, reopened] 6 | 7 | jobs: 8 | status_checker_job: 9 | name: Look for build warnings 10 | runs-on: ubuntu-latest 11 | permissions: 12 | statuses: write 13 | issues: write 14 | pull-requests: write 15 | steps: 16 | - uses: actions/checkout@v3 17 | - uses: dotnet/docs-tools/actions/status-checker@main 18 | with: 19 | repo_token: ${{ secrets.GITHUB_TOKEN }} 20 | docs_path: "Contribute" 21 | url_base_path: "contribute" 22 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | log/ 2 | obj/ 3 | _site/ 4 | .optemp/ 5 | _themes*/ 6 | _repo.*/ 7 | 8 | .openpublishing.buildcore.ps1 -------------------------------------------------------------------------------- /.openpublishing.publish.config.json: -------------------------------------------------------------------------------- 1 | { 2 | "docsets_to_publish": [ 3 | { 4 | "docset_name": "ContributionGuide", 5 | "build_source_folder": "Contribute", 6 | "build_output_subfolder": "ContributionGuide", 7 | "locale": "en-us", 8 | "monikers": [], 9 | "moniker_ranges": [], 10 | "xref_query_tags": [ 11 | "/dotnet", 12 | "/uwp/api" 13 | ], 14 | "open_to_public_contributors": true, 15 | "type_mapping": { 16 | "Conceptual": "Content", 17 | "ManagedReference": "Content", 18 | "RestApi": "Content", 19 | "ZonePivotGroups": "Toc" 20 | }, 21 | "build_entry_point": "docs", 22 | "template_folder": "_themes" 23 | }, 24 | { 25 | "docset_name": "ai-navigator", 26 | "build_source_folder": "ai-navigator", 27 | "build_output_subfolder": "ai-navigator", 28 | "locale": "en-us", 29 | "monikers": [], 30 | "moniker_ranges": [], 31 | "open_to_public_contributors": false, 32 | "type_mapping": { 33 | "Conceptual": "Content" 34 | }, 35 | "build_entry_point": "docs", 36 | "template_folder": "_themes" 37 | 38 | } 39 | ], 40 | "notification_subscribers": [], 41 | "branches_to_filter": [], 42 | "git_repository_branch_open_to_public_contributors": "main", 43 | "need_preview_pull_request": true, 44 | "need_pr_comments": true, 45 | "dependent_repositories": [ 46 | { 47 | "path_to_root": "_themes", 48 | "url": "https://github.com/Microsoft/templates.docs.msft", 49 | "branch": "main", 50 | "branch_mapping": {} 51 | }, 52 | { 53 | "path_to_root": "_themes.pdf", 54 | "url": "https://github.com/Microsoft/templates.docs.msft.pdf", 55 | "branch": "main", 56 | "branch_mapping": {} 57 | }, 58 | { 59 | "path_to_root": "contribute/guide", 60 | "url": "https://github.com/MicrosoftDocs/docs-help-pr", 61 | "branch": "main", 62 | "branch_mapping": {} 63 | } 64 | ], 65 | "branch_target_mapping": { 66 | "live": [ 67 | "Publish", 68 | "Pdf" 69 | ], 70 | "main": [ 71 | "Publish", 72 | "Pdf" 73 | ] 74 | }, 75 | "targets": { 76 | "Pdf": { 77 | "template_folder": "_themes.pdf" 78 | } 79 | }, 80 | "docs_build_engine": {}, 81 | "skip_source_output_uploading": false, 82 | "contribution_branch_mappings": {}, 83 | "need_generate_pdf_url_template": true 84 | } 85 | -------------------------------------------------------------------------------- /.vscode/extensions.json: -------------------------------------------------------------------------------- 1 | { 2 | "recommendations": [ 3 | "docsmsft.docs-authoring-pack" 4 | ] 5 | } 6 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "cSpell.words": [ 3 | "Hacktoberfest" 4 | ] 5 | } -------------------------------------------------------------------------------- /CODEOWNERS: -------------------------------------------------------------------------------- 1 | # These owners will be the default owners for everything in the repo. Unless a later match takes precedence 2 | * @mikekinsman @jehchow @Kiranchandratrey 3 | -------------------------------------------------------------------------------- /Contribute/breadcrumb/toc.yml: -------------------------------------------------------------------------------- 1 | items: 2 | - name: Learn 3 | tocHref: / 4 | topicHref: / 5 | items: 6 | - name: Contribute 7 | tocHref: /Contribute/ 8 | topicHref: /Contribute/index 9 | items: 10 | - name: Contributor guide 11 | tocHref: /Contribute/content 12 | topicHref: /Contribute/content 13 | -------------------------------------------------------------------------------- /Contribute/content/TOC.yml: -------------------------------------------------------------------------------- 1 | - name: Contributor guide overview 2 | href: index.md 3 | - name: Edit documentation 4 | items: 5 | - name: Overview 6 | href: how-to-write-overview.md 7 | - name: Edit in the browser 8 | href: how-to-write-quick-edits.md 9 | - name: Work locally 10 | items: 11 | - name: 1. Install Git and Markdown tools 12 | href: get-started-setup-tools.md 13 | - name: 2. Set up a local Git repository 14 | href: get-started-setup-local.md 15 | - name: 3. Make major changes 16 | href: how-to-write-major-edits.md 17 | - name: 4. Create a pull request 18 | href: create-pull-request.md 19 | - name: Process a pull request 20 | href: process-pull-request.md 21 | - name: Git and GitHub fundamentals 22 | href: git-github-fundamentals.md 23 | - name: Write for Hacktoberfest 24 | href: hacktoberfest.md 25 | - name: Review pull requests 26 | href: how-to-review-pull-request.md 27 | - name: Provide feedback on content 28 | href: provide-feedback.md 29 | - name: Create GitHub issues 30 | href: how-to-create-github-issues.md 31 | - name: Create and manage Collections 32 | href: collections.md 33 | - name: Respond to Q&A 34 | href: qna-overview.md 35 | - name: Connect with other experts in Tech Community 36 | href: https://techcommunity.microsoft.com/t5/microsoft-learn/ct-p/MicrosoftLearn 37 | #- name: Contributor program (future topic) 38 | # items: 39 | # - name: Overview 40 | # - name: Contributor stories program 41 | - name: Writing resources 42 | items: 43 | - name: Markdown reference 44 | href: markdown-reference.md 45 | displayName: alerts notes tips important caution warnings apostrophes quotation marks quotes blockquotes bold italic code snippets columns headings html images includes links lists bullets bulleted checklist numbered next steps button localize non-localized section selector superscript subscript table tables tabs tabbed videos icons 46 | - name: SEO reference 47 | href: seo-reference.md 48 | displayName: search engine optimization, SEO, discoverability 49 | - name: Style and voice quickstart 50 | href: style-quick-start.md 51 | - name: Microsoft Writing Style Guide 52 | href: /style-guide/ 53 | - name: Add code to articles 54 | href: code-in-docs.md 55 | displayName: backtick, code blocks, inline code blocks, repo snippet reference, !code-, interactive code snippets, programming languages, languages, code extensions, extensions 56 | - name: Format text 57 | href: text-formatting-guidelines.md 58 | displayName: text formatting, bold, italics, code style, code blocks, inline code, placeholders, headings, link text, keys, keyboard shortcuts, shortcuts 59 | - name: Links 60 | href: how-to-write-links.md 61 | displayName: link text, links from one article to another, link to another article, bookmarks, xref, cross reference, includes, links from includes, links in selectors, selectors, reference links, links to other pages, links to third party 62 | - name: Metadata 63 | href: metadata.md 64 | - name: Learn Authoring pack 65 | items: 66 | - name: Overview 67 | href: how-to-write-docs-auth-pack.md 68 | - name: Features 69 | items: 70 | - name: Dev lang completion 71 | href: docs-authoring/dev-lang-completion.md 72 | - name: Image compression 73 | href: docs-authoring/image-compression.md 74 | - name: Metadata explorer 75 | href: docs-authoring/metadata-explorer.md 76 | - name: Metadata updates 77 | href: docs-authoring/metadata-updates.md 78 | - name: Reformat Markdown tables 79 | href: docs-authoring/reformat-table.md 80 | - name: Smart quote replacement 81 | href: docs-authoring/smart-quote-replacement.md 82 | - name: Sort redirects 83 | href: docs-authoring/sort-redirects.md 84 | - name: Sort selection 85 | href: docs-authoring/sort-selection.md 86 | - name: Jupyter notebooks 87 | href: docs-authoring/jupyter-notebooks.md 88 | - name: Documentation set-specific guidance 89 | items: 90 | - name: .NET docs 91 | items: 92 | - name: How to contribute 93 | href: dotnet/dotnet-contribute.md 94 | - name: Labels, projects, and milestones roadmap 95 | href: dotnet/labels-projects.md 96 | - name: Style conventions 97 | href: dotnet/dotnet-style-guide.md 98 | - name: Voice and tone guide 99 | href: dotnet/dotnet-voice-tone.md 100 | - name: API reference guidelines 101 | href: dotnet/api-documentation.md 102 | - name: Pull request review process 103 | href: dotnet/dotnet-pr-review.md 104 | - name: Code analysis docs 105 | href: dotnet/dotnet-contribute-code-analysis.md 106 | - name: .NET naming in docs 107 | href: dotnet/net-core-5-naming.md 108 | - name: Patterns and Practices (AAC, WAF, CAF) 109 | href: architecture-center/aac-contribute.md 110 | - name: PowerShell-Docs 111 | href: powershell-overview.md 112 | -------------------------------------------------------------------------------- /Contribute/content/architecture-center/aac-contribute.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Contribute to Azure Patterns and Practices content 3 | description: This article describes how to contribute to Azure Patterns and Practices repositories. 4 | ms.topic: contributor-guide 5 | ms.service: learn 6 | ms.custom: external-contributor-guide 7 | author: lnyswonger 8 | ms.author: lnyswonger 9 | ms.date: 06/07/2024 10 | --- 11 | 12 | # Azure Patterns and Practices contributions 13 | 14 | Azure Patterns and Practices content helps customers design, build, and operate solutions on Azure. The content comprises three content portfolios listed below. Contributions are encouraged through GitHub pull requests. 15 | 16 | | Portfolio | Summary | Repository | 17 | |-----------|---------|------------| 18 | | Azure Architecture Center | Guidance for architecting solutions on Azure using established patterns and practices, incorporating the five pillars of architectural excellence. Use the technology choices and guides to determine the services that are right for your workload's requirements. | [https://github.com/MicrosoftDocs/architecture-center](https://github.com/MicrosoftDocs/architecture-center) | 19 | | Azure Well-Architected Framework | A set of guiding tenets to improve the quality of a workload. The framework consists of five pillars of architectural excellence to help produce a high-quality, stable, and efficient cloud architecture: reliability, security, cost optimization, operational excellence, and performance efficiency. | [https://github.com/MicrosoftDocs/well-architected](https://github.com/MicrosoftDocs/well-architected) | 20 | | Cloud Adoption Framework for Azure | A full lifecycle framework that enables cloud architects, IT professionals, and business decision-makers to achieve their cloud-adoption goals. Best practices, documentation, and tools help you create and implement business and technology strategies for the cloud. | [https://github.com/MicrosoftDocs/cloud-adoption-framework](https://github.com/MicrosoftDocs/cloud-adoption-framework) | 21 | 22 | ## Propose changes to an article 23 | 24 | You can propose small changes to content if you want to correct a typo or error, add a link, or add more details. Ensure that your contribution is technically accurate and provides helpful or valuable information in the context of the article. To get started, select the "Edit this document" pencil icon in the upper-right corner of the page you'd like to contribute to. See [Edit Microsoft Learn documentation](../how-to-write-quick-edits.md) for more details. 25 | 26 | If you can't directly propose changes through GitHub, you can also use the [feedback experience](../provide-feedback.md) at the bottom of the article you'd like to see improved. Please leave a detailed description of the change you'd like to see and why. 27 | -------------------------------------------------------------------------------- /Contribute/content/create-pull-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Create a pull request in GitHub 3 | description: Learn how to create a pull request in GitHub so your updates to Microsoft Learn documentation can be reviewed and published on Microsoft Learn. 4 | author: carlyrevier 5 | ms.author: cahublou 6 | ms.topic: contributor-guide 7 | ms.service: learn 8 | ms.custom: external-contributor-guide 9 | ms.date: 01/25/2024 10 | --- 11 | 12 | # Create a pull request in GitHub 13 | 14 | After you've updated or added your content, it's time to create a pull request (PR). This step is required for getting your changes published. For more background on PRs, see [Git and GitHub fundamentals](git-github-fundamentals.md#pull-requests). 15 | 16 | ## Prerequisites 17 | 18 | - Identify the GitHub repo that stores the documentation you want to edit. 19 | - [Create a GitHub account](index.md#create-a-github-account), if you don't have one. 20 | - [Install Git and Markdown tools](get-started-setup-tools.md). 21 | - [Set up a local Git repository](get-started-setup-local.md). 22 | - [Make changes in your local clone](how-to-write-major-edits.md) 23 | - [Review Git and GitHub fundamentals](git-github-fundamentals.md) (optional). 24 | 25 | ## Open a PR 26 | 27 | 1. In your browser, navigate to GitHub. 28 | 29 | 1. In the top-right, select your profile, and then select **Your repositories**. 30 | 31 | 1. Look for the repository in which you just made changes. If there's more than one, select the repository for the MicrosoftDocs upstream repository (for example, *MicrosoftDocs/azure-docs*). 32 | 33 | 1. Select the **Pull requests** tab at the top of the page. 34 | 35 | 1. If you see a green **Compare & pull request** button, select that button. 36 | 37 | :::image type="content" source="media/create-pull-request/create-pr-compare.png" alt-text="Screenshot of the compare and pull request button in GitHub."::: 38 | 39 | 1. If you don't see the button, open a new PR manually: 40 | 1. Select the green **New pull request** button. 41 | 1. On the Comparing changes page, make sure the **head repository:** drop-down is set to your fork (for example, *your-github-id/azure-docs*). 42 | 1. Change the **compare:** drop-down to your working branch. 43 | 1. Review the changes that appear. If you don't see your changes, make sure you're comparing the correct branches. 44 | 45 | 1. On the **Open a pull request** page, verify that: 46 | 47 | - The **base repository:** matches the upstream repository (for example, *MicrosoftDocs/azure-docs*). 48 | - The **base:** branch is set to the default branch (most likely named *main*) in the upstream repository. All your changes will be merged to the upstream branch. 49 | - The number of commits and files changed is what you expect. 50 | 51 | :::image type="content" source="media/create-pull-request/comparing-changes.png" alt-text="Screenshot of the Comparing changes screen in GitHub."::: 52 | 53 | 1. Your first commit message on your branch becomes the default PR title. If you want, edit the title to make it more appropriate for a PR (for example: Update prerequisites list). 54 | 55 | 1. Add an optional description. A description helps reviewers understand the purpose of your PR. For example, you can describe the problem you're trying to solve or the reason you're making the change. 56 | 57 | 1. Select **Create pull request**. The new PR is linked to your working branch in your fork. Until the PR is merged, any new commits you push to the same working branch in your fork are automatically included in the PR. 58 | 59 | ## Next steps 60 | 61 | You've now created your PR, but you haven't submitted it yet. Now you're ready to [process your pull request](process-pull-request.md) to make sure it gets reviewed and merged into the default branch. -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/dev-lang-completion.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Dev lang completion - Learn Authoring Pack 3 | description: Learn how dev lang completion assists contributors in the Learn Authoring Pack, Visual Studio Code extension. 4 | author: scottaddie 5 | ms.service: learn 6 | ms.topic: contributor-guide 7 | ms.date: 03/03/2020 8 | ms.author: scaddie 9 | --- 10 | 11 | # Dev lang completion 12 | 13 | [!INCLUDE [markdown-extension](includes/markdown-extension.md)] 14 | 15 | ## Summary 16 | 17 | Contributors need assistance determining the valid language identifiers (dev langs) that can follow triple-backticks (code fence openings) in a Markdown file. Unfortunately, build-time validation of dev langs doesn't exist. The result is disparate representations of a single language within the same conceptual docset. 18 | 19 | Consider C# as an example. Contributors have used `c#`, `C#`, `cs`, `csharp`, and others as dev lang representations of the language. Which of the preceding representations is correct? 20 | 21 | The *Dev lang completion* feature dispels the confusion by displaying a list of known dev langs. Upon selecting a dev lang name from IntelliSense: 22 | 23 | * The code fence is closed. 24 | * The caret is positioned in the code fence. 25 | 26 | ## Preferences 27 | 28 | It's not possible to disable this feature. The following settings are available: 29 | 30 | * [Display commonly used dev langs](#display-commonly-used-dev-langs) 31 | * [Display all known dev langs](#display-all-known-dev-langs) 32 | 33 | ### Display commonly used dev langs 34 | 35 | Only a subset of the valid dev langs will be used in a single docset. To enhance the user experience: 36 | 37 | 1. In Visual Studio Code, open the docset to the root directory. 38 | 1. Select **File** > **Preferences** > **Settings** and filter by *Learn Markdown Extension*. 39 | 1. Click the **Edit in settings.json** link in the **Markdown: Docset Languages** section. 40 | 1. Add the following `markdown.docsetLanguages` property to the *settings.json* file: 41 | 42 | ```json 43 | { 44 | "markdown.docsetLanguages": [ 45 | 46 | ] 47 | } 48 | ``` 49 | 50 | 1. Position your caret in the property's empty array, and activate IntelliSense (via Ctrl + Space). A list of known dev lang names appears. 51 | 1. Add dev lang names to the array until you're satisfied with the list. For example, the following list will display four dev lang names to the user after typing triple-ticks: 52 | 53 | ```json 54 | { 55 | "markdown.docsetLanguages": [ 56 | ".NET Core CLI", 57 | "C#", 58 | "Markdown", 59 | "YAML" 60 | ] 61 | } 62 | ``` 63 | 64 | 1. Save your changes to the *settings.json* file. 65 | 66 | > [!WARNING] 67 | > An empty `markdown.docsetLanguages` array causes all known dev langs to display. 68 | 69 | ### Display all known dev langs 70 | 71 | By default, all known dev lang names are displayed in IntelliSense. This setting overrides the `markdown.docsetLanguages` property described in [Display commonly used dev langs](#display-commonly-used-dev-langs). 72 | 73 | To change this setting: 74 | 75 | 1. Select **File** > **Preferences** > **Settings** and filter by *Learn Markdown Extension*. 76 | 1. Toggle the setting in the **Markdown: All Available Languages** section. 77 | 78 | ## In action 79 | 80 | Below is a brief demonstration of this feature: 81 | 82 | [![Dev lang completion](media/dev-lang-completion.gif)](media/dev-lang-completion.gif#lightbox) 83 | -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/image-compression.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Image Compression - Learn Authoring Pack 3 | description: Learn how to compress images within the Learn Authoring Pack, Learn Images extension. 4 | author: IEvangelist 5 | ms.service: learn 6 | ms.topic: contributor-guide 7 | ms.date: 03/31/2023 8 | ms.author: dapine 9 | --- 10 | 11 | # Image compression 12 | 13 | [!INCLUDE [image-extension](includes/image-extension.md)] 14 | 15 | ## Summary 16 | 17 | All documentation is provided via the web, with the exception of PDF versions of documentation articles. When serving static content, it's best to minimize the number of bytes sent over the wire. One way to do that is to compress images at rest. 18 | 19 | The Learn Images extension within the Learn Authoring Pack includes image compression context menu items. The following image types / extensions are supported: 20 | 21 | * *\*.png* 22 | * *\*.jpg* 23 | * *\*.jpeg* 24 | * *\*.gif* 25 | * *\*.svg* 26 | * *\*.webp* 27 | 28 | The lossless image compression algorithms are used, where applicable. 29 | 30 | ## Compress image 31 | 32 | From the **Explorer** navigation pane, right-click on an image file - then select the **Compress image** option. The image is then compressed. 33 | 34 | ## Compress images in folder 35 | 36 | From the **Explorer** navigation pane, right-click on a folder containing images - then select the **Compress images in folder** option. All images in the folder are compressed. 37 | 38 | ## Considerations 39 | 40 | Large resolution images are implicitly resized. The maximum dimensions are based on the platform suggested max width of `1,200px`. The max is only used when images are larger than they're recommended to be. They maintain the aspect ratio when automatically resized. 41 | 42 | ## Preferences 43 | 44 | The maximum dimensions are configurable, but a default max width of `1200` pixels exists. To configure the max dimensions, select **File -> Preferences -> Settings** and filter by `"Learn Images Extension"`. 45 | 46 | :::image type="content" source="media/configure-image-compression.png" alt-text="Configure image compression"::: 47 | 48 | > [!NOTE] 49 | > A value of `0` in either the **Max Width** or **Max Height** will simply ignore resolution variances. 50 | 51 | ## In action 52 | 53 | Below is a brief demonstration of this feature. 54 | 55 | [![Compress image demo](media/compress-image.gif)](media/compress-image.gif#lightbox) 56 | -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/includes/image-extension.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: IEvangelist 3 | ms.service: learn 4 | ms.topic: contributor-guide 5 | ms.date: 09/27/2022 6 | ms.author: dapine 7 | --- 8 | 9 | ## Extension name 10 | 11 | The Learn Authoring Pack is comprised of multiple sub extensions. This image feature is included in the Learn Images extension. It's automatically included in the Learn Authoring Pack, so there's no need to install it separately. 12 | -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/includes/markdown-extension.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: IEvangelist 3 | ms.service: learn 4 | ms.topic: contributor-guide 5 | ms.date: 03/11/2021 6 | ms.author: dapine 7 | --- 8 | 9 | ## Extension name 10 | 11 | The Learn Authoring Pack, Visual Studio Code meta extension is comprised of multiple sub extensions. This feature is included in the Learn Markdown extension. The Learn Markdown extension is part of the Learn Authoring Pack, there is no need to install it separately. 12 | -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/jupyter-notebooks.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Get content from Jupyter notebooks - Learn Authoring Pack 3 | description: Learn how to insert and update content from a Jupyter notebook into your document with the Learn Authoring Pack, Visual Studio Code extension. 4 | author: sdgilley 5 | ms.service: learn 6 | ms.topic: contributor-guide 7 | ms.date: 01/03/2023 8 | ms.author: sgilley 9 | --- 10 | 11 | # Insert and update content from a Jupyter notebook 12 | 13 | [!INCLUDE [markdown-extension](includes/markdown-extension.md)] 14 | 15 | > [!IMPORTANT] 16 | > Insert and update from a Jupyter notebook functionality does not currently work on a Mac. 17 | 18 | ## Summary 19 | 20 | Jupyter Notebooks are a standard interactive way of creating and sharing code in the Python world. The notebook contains a combination of Python code, markdown, and optionally output from the code. 21 | 22 | 23 | The Learn Authoring Pack extension includes functionality to put a static markdown version of a Jupyter notebook into your document: 24 | 25 | **Learn: Insert Jupyter notebook**: Enter the URL of the notebook. A markdown version of the notebook is added to the document at the position of your cursor. Do not modify the start or end tags; it's what the next function uses to update the notebook. 26 | 27 | **Learn: Update Jupyter notebook**: This function will replace the previously inserted notebook content between start and end with the latest version. No need to enter the URL, it's recorded in the start tag. Update functionality assumes there is a single notebook in the document. Don't add multiple notebooks to a single document. 28 | 29 | ## Access the functions 30 | 31 | * Type **Ctrl + Shift + P** to open the Command Palette, then start to type the name of the function until you see it. Select the function. 32 | * You can also access **Insert Jupyter notebook** from the the Learn Markdown Authoring menu by typing **Alt + M**. Scroll down to find **Jupyter Notebook**. 33 | 34 | ## In action 35 | 36 | Below is a brief demonstration of this feature. 37 | 38 | [![Insert Jupyter notebook](media/insertnotebook.gif)](media/insertnotebook.gif#lightbox) 39 | 40 | ## Troubleshooting 41 | 42 | > [!IMPORTANT] 43 | > Insert and update from a Jupyter notebook functionality does not currently work on a Mac. 44 | 45 | These functions need Python, `jupyter`, and `nbconvert` installed on your machine. 46 | 47 | To see if Python is installed, open a VS Code terminal and run: 48 | 49 | * Windows - `where python` 50 | * Linux/Mac - `which python` 51 | 52 | If the return is one or more paths, Python is installed. If not, [install Python](https://www.python.org/downloads/) now. 53 | 54 | Next make sure `jupyter` is installed: 55 | 56 | * Windows - `where jupyter` 57 | * Linux/Mac - `which jupyter` 58 | 59 | If a path is not returned, install `jupyter`: 60 | 61 | ```bash 62 | pip install --upgrade jupyter 63 | ``` 64 | 65 | Once both Python and `jupyter` are installed, install `nbconvert`: 66 | 67 | ```bash 68 | pip install --upgrade nbconvert 69 | ``` 70 | -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/compress-image.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/compress-image.gif -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/configure-image-compression.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/configure-image-compression.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/dev-lang-completion.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/dev-lang-completion.gif -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/globe-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/globe-icon.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/insertnotebook.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/insertnotebook.gif -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/json-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/json-icon.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/markdown-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/markdown-icon.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/metadata-explorer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/metadata-explorer.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/metadata-hover.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/metadata-hover.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/reformat-table-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/reformat-table-menu.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/reformat-table.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/reformat-table.gif -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/replace-smart-quotes.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/replace-smart-quotes.gif -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/show-gauntlet-bar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/show-gauntlet-bar.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/sort-redirect.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/sort-redirect.gif -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/sort-selection-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/sort-selection-menu.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/sort-selection.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/sort-selection.gif -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/update-metadata-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/update-metadata-menu.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/update-metadata.gif: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/update-metadata.gif -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/media/warning-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/docs-authoring/media/warning-icon.png -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/metadata-explorer.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Metadata explorer - Learn Authoring Pack 3 | description: Learn about the Metadata explorer, included with the Learn Authoring Pack Visual Studio Code extension. 4 | author: gewarren 5 | ms.author: gewarren 6 | ms.service: learn 7 | ms.topic: contributor-guide 8 | ms.date: 06/10/2021 9 | feedback_product_url: https://github.com/microsoft/vscode-docs-authoring/issues 10 | --- 11 | 12 | # Metadata explorer 13 | 14 | [!INCLUDE [markdown-extension](includes/markdown-extension.md)] 15 | 16 | ## Summary 17 | 18 | The Metadata explorer appears automatically in the Explorer sidebar of Visual Studio Code when you open a Learn Markdown file. 19 | 20 | :::image type="content" source="media/metadata-explorer.PNG" alt-text="Metadata explorer in Visual Studio Code"::: 21 | 22 | ## Metadata sources 23 | 24 | The Metadata explorer shows metadata from three sources: the YAML front matter of the Markdown file that's open in the editor, and the `fileMetadata` and `globalMetadata` sections of the docset's *docfx.json* file. Icons help to quickly identify the source of the displayed metadata. If your article is missing any required metadata, that metadata key appears with a warning icon. 25 | 26 | | Icon | Metadata source | 27 | | - | - | 28 | | :::image type="content" source="media/markdown-icon.png" alt-text="Markdown icon"::: | YAML front matter of active Markdown file | 29 | | :::image type="content" source="media/json-icon.png" alt-text="Json icon"::: | [`fileMetadata` section](https://github.com/dotnet/docs/blob/d34042d234a90d74df1baee17f664f89d5abd67f/docfx.json#L147) of *docfx.json* file | 30 | | :::image type="content" source="media/globe-icon.png" alt-text="Globe icon"::: | [`globalMetadata` section](https://github.com/dotnet/docs/blob/d34042d234a90d74df1baee17f664f89d5abd67f/docfx.json#L111) of *docfx.json* file | 31 | | :::image type="content" source="media/warning-icon.png" alt-text="Warning icon"::: | This required metadata is *missing completely* | 32 | 33 | ## Precedence 34 | 35 | The Metadata explorer only shows unique metadata keys. If more than one value can apply for the same key, the explorer uses the same precedence settings as DocFx does. The order of precedence in decreasing priority is: 36 | 37 | 1. YAML front matter 38 | 1. `fileMetadata` 39 | 1. `globalMetadata` 40 | 41 | If multiple folder-based glob patterns apply to a single article, the entry that appears last in the *docfx.json* file is selected. For example, consider the file at *C:/docs/csharp/reference/keywords.md* and the following entries in the *docfx.json* file: 42 | 43 | ```json 44 | "ms.topic": { 45 | "csharp/**/*.md": "conceptual", 46 | "csharp/reference/*.md": "language-reference" 47 | } 48 | ``` 49 | 50 | In this case, while both glob patterns include the path to the file, the second value of `language-reference` is selected. 51 | 52 | ## Tooltip 53 | 54 | You can hover over a value to see an expanded display in the tooltip. This is especially useful for keys that have multiple values in an array. The information also includes the [source](#metadata-sources) of the metadata. 55 | 56 | :::image type="content" source="media/metadata-hover.PNG" alt-text="Tooltip for metadata value in Metadata explorer."::: 57 | 58 | ## Refresh 59 | 60 | If you have auto-save disabled in Visual Studio Code, the Metadata explorer refreshes automatically when you save your Markdown file. If you have auto-save enabled, you can refresh the displayed metadata by clicking the **Refresh** button at the top of the explorer. 61 | 62 | When you open a different Markdown file, the explorer refreshes automatically. 63 | 64 | ## See also 65 | 66 | - [Metadata](../metadata.md) 67 | -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/metadata-updates.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Metadata Updates - Learn Authoring Pack 3 | description: Learn how to update metadata from the Learn Authoring Pack, Visual Studio Code extension. 4 | author: IEvangelist 5 | ms.service: learn 6 | ms.topic: contributor-guide 7 | ms.date: 03/03/2020 8 | ms.author: dapine 9 | --- 10 | 11 | # Update metadata 12 | 13 | [!INCLUDE [markdown-extension](includes/markdown-extension.md)] 14 | 15 | ## Summary 16 | 17 | In a Markdown (*\*.md*) file, there are two contextual menu items specific to metadata. When you right-click anywhere in the text editor, you will see something similar to the following menu items: 18 | 19 | :::image type="content" source="media/update-metadata-menu.png" alt-text="Update metadata context menu"::: 20 | 21 | ## Update `ms.date` metadata value 22 | 23 | Selecting the **Update `ms.date` Metadata Value** option will set the current Markdown files `ms.date` value to today's date. If the document does not have an `ms.date` metadata field, no action is taken. 24 | 25 | ## Update implicit metadata values 26 | 27 | Selecting the **Update implicit metadata values** option will find and replace all possible metadata values that could be implicitly specified. Metadata values are implicitly specified in the *docfx.json* file, under the `build/fileMetadata` node. Each key value pair in the `fileMetadata` node represents metadata defaults. For example, a Markdown file in the *top-level/sub-folder* directory that omits the `ms.author` metadata value could implicitly specify a default value to use in the `fileMetadata` node. 28 | 29 | ```json 30 | { 31 | "build": { 32 | "fileMetadata": { 33 | "ms.author": { 34 | "top-level/sub-folder/**/**.md": "dapine" 35 | } 36 | } 37 | } 38 | } 39 | ``` 40 | 41 | In this case, all Markdown files would implicitly take on the `ms.author: dapine` metadata value. The feature acts on these implicit settings found in the *docfx.json* file. If a Markdown file contains metadata with values that are explicitly set to something other than the implicit values, they are overridden. 42 | 43 | Consider the following Markdown file metadata, where this Markdown file resides in **top-level/sub-folder/includes/example.md**: 44 | 45 | ```markdown 46 | --- 47 | ms.author: someone-else 48 | --- 49 | 50 | # Content 51 | ``` 52 | 53 | If the **Update implicit metadata values** option was executed on this file, with the assumed *docfx.json* content from above the metadata value would be updated to `ms.author: dapine`. 54 | 55 | ```markdown 56 | --- 57 | ms.author: dapine 58 | --- 59 | 60 | # Content 61 | ``` 62 | 63 | ## In action 64 | 65 | Below is a brief demonstration of this feature. 66 | 67 | [![Update metadata demo](media/update-metadata.gif)](media/update-metadata.gif#lightbox) 68 | -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/reformat-table.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Reformat Markdown Tables - Learn Authoring Pack 3 | description: Learn how to use the various Markdown table formatting features from the Learn Authoring Pack, Visual Studio Code extension. 4 | author: IEvangelist 5 | ms.service: learn 6 | ms.topic: contributor-guide 7 | ms.date: 03/03/2020 8 | ms.author: dapine 9 | --- 10 | 11 | # Reformat Markdown tables 12 | 13 | [!INCLUDE [markdown-extension](includes/markdown-extension.md)] 14 | 15 | ## Summary 16 | 17 | In a Markdown (*\*.md*) file, when you select a complete table - two table formatting context menu items are now available. Right-click on the selected Markdown table to open the context menu. You will see something similar to the following menu items: 18 | 19 | :::image type="content" source="media/reformat-table-menu.png" alt-text="Reformat table context menu"::: 20 | 21 | > [!TIP] 22 | > This feature **does not** work with multiple table selections, but rather is intended for a single Markdown table. You must select the entire table, including headings for desired results. 23 | 24 | ## Consolidate selected table 25 | 26 | Selecting the **Consolidate selected table** option will collapse the table headings and contents with only a single space on either side of each value. 27 | 28 | ## Evenly distribute selected table 29 | 30 | Selecting the **Evenly distribute selected table** option will calculate the longest value in each column and evenly distribute all the other values accordingly with space. 31 | 32 | ## Considerations 33 | 34 | The feature will not impact the rendering of the table, but it will help to improve the readability of the table - thus making more maintainable. The reformatting table feature will keep column alignment intact. 35 | 36 | Consider the following table: 37 | 38 | ```markdown 39 | | Column1 | This is a long column name | Column3 | | 40 | |--:|---------|:--:|:----| 41 | || | | | 42 | | | | | a value | 43 | || | | | 44 | | | | This is a long value | but why? | 45 | | | | | | 46 | | | | | Here is something | 47 | | | | | | 48 | ``` 49 | 50 | After being "evenly distributed": 51 | 52 | ```markdown 53 | | Column1 | This is a long column name | Column3 | | 54 | |--------:|----------------------------|:--------------------:|:------------------| 55 | | | | | | 56 | | | | | a value | 57 | | | | | | 58 | | | | This is a long value | but why? | 59 | | | | | | 60 | | | | | Here is something | 61 | | | | | | 62 | ``` 63 | 64 | After being "consolidated": 65 | 66 | ```markdown 67 | | Column1 | This is a long column name | Column3 | | 68 | |-:|--|:-:|:-| 69 | | | | | | 70 | | | | | a value | 71 | | | | | | 72 | | | | This is a long value | but why? | 73 | | | | | | 74 | | | | | Here is something | 75 | | | | | | 76 | ``` 77 | 78 | ## In action 79 | 80 | Below is a brief demonstration of this feature. 81 | 82 | [![Reformat table demo](media/reformat-table.gif)](media/reformat-table.gif#lightbox) 83 | -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/smart-quote-replacement.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Automatic Smart Quote Replacements - Learn Authoring Pack 3 | description: Learn how to automatically replace smart quote with the Learn Authoring Pack, Visual Studio Code extension. 4 | author: IEvangelist 5 | ms.service: learn 6 | ms.topic: contributor-guide 7 | ms.date: 03/03/2020 8 | ms.author: dapine 9 | --- 10 | 11 | # Smart quote replacement 12 | 13 | [!INCLUDE [markdown-extension](includes/markdown-extension.md)] 14 | 15 | ## Summary 16 | 17 | Content developers are responsible for authoring some of the most advanced features of modern technology and intelligence, yet our tooling today prefers the usage of "dumb quotes" in Markdown. The antonym of course being "smart quotes". Smart quotes are common with ideal typographies, but not preferred with Markdown and rendered HTML. 18 | 19 | When working on a Microsoft Word document for example, you may have noticed that when you hold the Shift and type a " Microsoft Word quickly replaces the `"` character with a smart quote equivalent `“` character. 20 | 21 | | Description | Unicode | Smart Quote | Replacement | 22 | |--------------------|----------|-------------|-------------| 23 | | Double left quote | `\u201c` | `“` | `"` | 24 | | Double right quote | `\u201d` | `”` | `"` | 25 | | Single left quote | `\u2018` | `‘` | `'` | 26 | | Single right quote | `\u2019` | `’` | `'` | 27 | 28 | In a Markdown (*\*.md*) file, when you paste in text or as you update content - this feature will actively evaluate the content and automatically replace values accordingly. 29 | 30 | > [!NOTE] 31 | > The smart quote replacement feature also replaces other characters, such as but not limited to; (`©, ™, ®, •`, subscript and superscript characters). This is useful when pasting text from Word documents. 32 | 33 | ## Preferences 34 | 35 | This feature is optional, but defaults to `true`. To toggle this feature on or off: 36 | 37 | 1. Select **File** > **Preferences** > **Settings** and filter by *Learn Markdown Extension*. 38 | 1. Toggle the setting in the **Markdown: Replace Smart Quotes** section. 39 | 40 | ## In action 41 | 42 | Below is a brief demonstration of this feature. 43 | 44 | [![Replace smart quotes demo](media/replace-smart-quotes.gif)](media/replace-smart-quotes.gif#lightbox) 45 | -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/sort-redirects.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Sort Redirects - Learn Authoring Pack 3 | description: Learn how to Sort Redirects with the Learn Authoring Pack, Visual Studio Code extension. 4 | author: IEvangelist 5 | ms.service: learn 6 | ms.topic: contributor-guide 7 | ms.date: 03/03/2020 8 | ms.author: dapine 9 | --- 10 | 11 | # Sort redirects 12 | 13 | [!INCLUDE [markdown-extension](includes/markdown-extension.md)] 14 | 15 | ## Summary 16 | 17 | With the evolution of a docset, some Markdown files eventually will be deleted. When a Markdown file is deleted, we're required to provide a redirect so that any reference to the deleted article is properly resolved via the redirect. Redirections are specified in the *.openpublishing.redirection.json* file. 18 | 19 | 1. Open the Command Palette, press F1 (or ⇧⌘P on macOS) 20 | 1. Type: **Learn: Sort main redirection file** 21 | 1. Select the command to execute it 22 | 1. Observe changes to *.openpublishing.redirection.json* file 23 | 24 | ## Considerations 25 | 26 | The concept of "daisy chaining" exists with how the *.openpublishing.redirection.json* file was originally designed. Over time, files added as a redirect will eventually become stale. This happens when file A is deleted and needs a redirect to file B, then later file B is deleted and then redirects to file C. Ideally, both entries would point to C - so that A redirects to C, and B remains the same. This is a minor performance gain, and the feature is actively being worked on. 27 | 28 | ## In action 29 | 30 | Below is a brief demonstration of this feature. 31 | 32 | [![Sort redirects demo](media/sort-redirect.gif)](media/sort-redirect.gif#lightbox) 33 | -------------------------------------------------------------------------------- /Contribute/content/docs-authoring/sort-selection.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Sort Selection - Learn Authoring Pack 3 | description: Learn how to use the Sort Selection feature from the Learn Authoring Pack, Visual Studio Code extension. 4 | author: IEvangelist 5 | ms.service: learn 6 | ms.topic: contributor-guide 7 | ms.date: 03/03/2020 8 | ms.author: dapine 9 | --- 10 | 11 | # Sort selection 12 | 13 | [!INCLUDE [markdown-extension](includes/markdown-extension.md)] 14 | 15 | ## Summary 16 | 17 | In a Markdown (*\*.md*) file, when you've made a selection - two sorting context menu items are now available. Right-click on the selected text to open the context menu. You will see something similar to the following menu items: 18 | 19 | :::image type="content" source="media/sort-selection-menu.png" alt-text="Sort selection context menu"::: 20 | 21 | > [!TIP] 22 | > The sorting context menu items are hidden until there is a valid selection in the Visual Studio Code text editor. 23 | 24 | ## Sort selection ascending (A to Z) 25 | 26 | Selecting the **Sort selection ascending (A to Z)** option will sort the entire selection ascending, alphabetically from A to Z. 27 | 28 | ## Sort selection descending (Z to A) 29 | 30 | Selecting the **Sort selection descending (Z to A)** option will sort the entire selection ascending, alphabetically from Z to A. 31 | 32 | ## Considerations 33 | 34 | The underlying sorting mechanism uses *natural language* sorting. This makes it more powerful and comprehensive than standard sorting. Consider the following table: 35 | 36 | ```markdown 37 | | Column1 | Column2 | 38 | |---------|----------------------------------------| 39 | | 1 | Number 1 | 40 | | Aa | The first letter in the alphabet | 41 | | Ab | The first letter in the alphabet | 42 | | C | The a letter after A in the alphabet | 43 | | M | Somewhere in the middle? | 44 | | 2 | Number 2 | 45 | | X | The alphabet letter is towards the end | 46 | | Z | The last letter in the alphabet | 47 | | 11 | Number 11 | 48 | ``` 49 | 50 | Without natural language sorting, the order for `Column1` would have been 1, 11, 2, etc. but instead it understands that 11 is greater than 2 - resulting in the following ascending order: 51 | 52 | ```markdown 53 | | Column1 | Column2 | 54 | |---------|----------------------------------------| 55 | | 1 | Number 1 | 56 | | 2 | Number 2 | 57 | | 11 | Number 11 | 58 | | Aa | The first letter in the alphabet | 59 | | Ab | The first letter in the alphabet | 60 | | C | The a letter after A in the alphabet | 61 | | M | Somewhere in the middle? | 62 | | X | The alphabet letter is towards the end | 63 | | Z | The last letter in the alphabet | 64 | ``` 65 | 66 | ## In action 67 | 68 | Below is a brief demonstration of this feature. 69 | 70 | [![Sort selection demo](media/sort-selection.gif)](media/sort-selection.gif#lightbox) 71 | -------------------------------------------------------------------------------- /Contribute/content/dotnet/api-documentation.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: How to write /// docs for .NET API ref 3 | ms.date: 06/29/2023 4 | author: gewarren 5 | ms.author: gewarren 6 | ms.service: learn 7 | ms.topic: contributor-guide 8 | description: Learn how to write good descriptions in source code for generating .NET API reference documentation. 9 | --- 10 | # How to write good /// docs for .NET API reference 11 | 12 | The ultimate goal for .NET API docs is to have the /// XML comments in the .NET source code be the "source of truth". For MSBuild, ASP.NET Core, and EF Core, this goal has been met. However, currently the [dotnet-api-docs repo](https://github.com/dotnet/dotnet-api-docs) remains the source of truth for core .NET API reference. [This dotnet/runtime issue](https://github.com/dotnet/runtime/issues/44969) tracks the effort to backport .NET docs and make the [dotnet/runtime](https://github.com/dotnet/runtime) repo the source of truth. 13 | 14 | This article provides tips about writing good doc comments *within the source code itself*. 15 | 16 | ## Good comments make for good documents 17 | 18 | .NET API triple-slash comments are transformed into public documentation on learn.microsoft.com and also appear in IntelliSense in the IDE. The comments should be: 19 | 20 | - Complete—empty doc entries for methods, parameters, exceptions, and so on, make the APIs feel under-supported, temporary, or trivial. 21 | - Correct—readers scan for critical details and become frustrated when key information is missing or incorrect. 22 | - Contextual—readers land on this page from search and need to know how and when to use the API, and what the code implications are. 23 | - Polished—poor or hasty grammar and spelling can confuse the reader and make even simple calls ambiguous; also, poor presentation communicates low investment. 24 | 25 | ## Best practices 26 | 27 | 1. Use `cref` instead of `href` to link to another type or method. 28 | 29 | Correct: `An object.` 30 | 31 | Incorrect: `An object.` 32 | 33 | 1. When referencing parameters, wrap the parameter name in a `` tag, for example, `The offset in where the range begins.`. 34 | 1. If you have more than one paragraph in the doc comment, separate the paragraphs with `` tags. 35 | 1. Wrap code examples in `` tags within `` tags. 36 | 1. Use `` to add links to other APIs in the autogenerated "See Also" section. 37 | 38 | ## XML doc tags 39 | 40 | | Tag | Purpose | Example | 41 | | - | - | - | 42 | | `` | Adds a "See also" link to the specified API. | `` | 43 | | `` | Formats the specified text as code within a description. | `Gets the current version of the language compiler, in the form Major.Minor.Revision.Build.` | 44 | | `` | Formats multiple lines as code. | `using(logger.BeginScope("Processing request from {Address}", address)) { }` | 45 | | `` | Adds a code example under the "Example" H2 heading. | `using(logger.BeginScope("Processing request from {Address}", address)) { }` | 46 | | `` | Describes an exception the API can throw. | `No application identity is specified in .` | 47 | | `` | Refer to comments in another file that describe the APIs in your source code. | ``

[.NET MAUI example](https://github.com/dotnet/maui/blob/a064bf8dd9c74909e989fe007053fc05442a7465/src/Controls/src/Core/Layout/AbsoluteLayout.cs#L9) | 48 | | `` | Inherit XML comments from base classes, interfaces, and similar methods. | `` | 49 | | `` | Creates a bulleted or numbered list. | `Set the root path to the result.Load host configuration.` | 50 | | `` | Separates paragraphs. | | 51 | | `` | Refers to a method parameter. | `Returns the activity with the specified .` | 52 | | `` | Adds a "See also" link to the specified article. | `ADO.NET overview` | 53 | | `` | Links to another API. | `Describes the behavior that caused a event.` | 54 | | `` | Formats the specified text as code. | `Gets the value of the header for an HTTP response.` | 55 | | `` | Adds a "See also" link to the specified API. | `` | 56 | | `` | Refers to a type parameter. | `The is resolved from a scoped service provider.` | 57 | 58 | For more information, see [Recommended XML tags for C#](/dotnet/csharp/language-reference/xmldoc/recommended-tags) and the [C# specification](/dotnet/csharp/language-reference/language-specification/documentation-comments#d2-introduction). The [ECMAXML spec](http://docs.go-mono.com/index.aspx?link=man%3amdoc(5)) also has good information, although be aware that there are some differences between ECMAXML and /// documentation comments (for example, cref targets are fully expanded and have prefixes in ECMAXML). 59 | 60 | ## Cross references 61 | 62 | When you use a `` tag to link to another API, there's no need to add a prefix to the type name, such as `T:` for type or `M:` for method. In fact, code analysis [rule CA1200](/dotnet/fundamentals/code-analysis/quality-rules/ca1200) flags code comments that add a prefix to the type name in a `cref` tag. However, there are a couple exceptions to this rule: 63 | 64 | - When you want to link to the general form of a method that has more than one overload, the C# compiler [doesn't currently support that](https://github.com/dotnet/csharplang/issues/320). The workaround for docs is to prefix the method name with `O:` in source code (or `Overload:` in ECMAXML) and suppress [rule CA1200](/dotnet/fundamentals/code-analysis/quality-rules/ca1200). For example: ``. 65 | - When the API can't be resolved from the current context, which includes any `using` directives. In this case, use the fully qualified API name with a prefix. 66 | 67 | When the `` tag is converted to [ECMAXML](http://docs.go-mono.com/index.aspx?link=man%3amdoc(5)), mdoc replaces the type name with the full DocId of the API, which includes a prefix. 68 | 69 | ## Descriptions 70 | 71 | For authoritative guidelines about describing each symbol type and its various parts, see the [.NET API docs wiki](https://github.com/dotnet/dotnet-api-docs/wiki). 72 | 73 | ## Empty comments 74 | 75 | The well-known placeholder text for empty comments is `To be added.`. The Learn build system recognizes this text and removes it when the ECMAXML is converted into HTML, leaving an empty description. 76 | 77 | ## Separate code files 78 | 79 | If your code example is lengthy, you can put it in a separate file in the docs repo and link to it from source code in the following way: 80 | 81 | ```csharp 82 | /// 83 | /// 84 | /// 87 | /// 88 | ``` 89 | 90 | For some more details about how to hook up separate code files, see [this discussion](https://github.com/dotnet/runtime/pull/111177#discussion_r1907549328). 91 | 92 | ## Language attributes 93 | 94 | Language attributes on `` tags are optional, but they cause the code to be formatted with color coding. For example: 95 | 96 | ```csharp 97 | /// 98 | /// This sample shows the basic pattern for defining a typed client class. 99 | /// 100 | /// class ExampleClient 101 | /// { 102 | /// private readonly HttpClient _httpClient; 103 | /// private readonly ILogger _logger; 104 | /// 105 | /// // Typed clients can use constructor injection to access additional services. 106 | /// public ExampleClient(HttpClient httpClient, ILogger<ExampleClient> logger) 107 | /// { 108 | /// _httpClient = httpClient; 109 | /// _logger = logger; 110 | /// } 111 | /// } 112 | /// 113 | /// 114 | ``` 115 | 116 | ## Internal APIs 117 | 118 | When documenting an API that's not intended to be used by consumers, use wording similar to the following: 119 | 120 | `This type supports the .NET infrastructure and is not intended to be used directly from your code.` 121 | 122 | ## See also 123 | 124 | - [ECMAXML format](http://docs.go-mono.com/index.aspx?link=man%3amdoc(5)) 125 | - [Recommended XML tags for C#](/dotnet/csharp/language-reference/xmldoc/recommended-tags) 126 | - [Documentation comments (C# specification)](/dotnet/csharp/language-reference/language-specification/documentation-comments#d2-introduction) 127 | -------------------------------------------------------------------------------- /Contribute/content/dotnet/dotnet-contribute-code-analysis.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Contribute docs for .NET code analysis rules to the .NET docs repository 3 | description: This article describes the process for contributing to the articles and code samples for .NET code analysis rules in the .NET docs repository. 4 | author: mavasani 5 | ms.author: mavasani 6 | ms.topic: contributor-guide 7 | ms.service: learn 8 | ms.custom: external-contributor-guide 9 | ms.date: 10/09/2020 10 | --- 11 | # Contribute docs for .NET code analysis rules to the .NET docs repository 12 | 13 | .NET compiler platform (Roslyn) analyzers inspect your C# or Visual Basic code for code quality and code style issues. Starting in .NET 5.0, these analyzers are [included with the .NET SDK](/dotnet/fundamentals/code-analysis/overview). 14 | 15 | - [Code quality analysis ("CAxxxx" rules)](/dotnet/fundamentals/code-analysis/overview#code-quality-analysis): 16 | - Implemented [here](https://github.com/dotnet/roslyn-analyzers/tree/main/src/NetAnalyzers) in `dotnet/roslyn-analyzers` repo. 17 | - Documented [here](https://github.com/dotnet/docs/blob/main/docs/fundamentals/code-analysis/quality-rules) in the `dotnet/docs` repo. See [Contribute docs for 'CAxxxx' rules](#contribute-docs-for-caxxxx-rules). 18 | - [Code style analysis ("IDExxxx" rules)](/dotnet/fundamentals/code-analysis/overview#code-style-analysis): 19 | - Implemented [here](https://github.com/dotnet/roslyn/tree/main/src/Analyzers) in `dotnet/roslyn` repo. 20 | - Documented [here](https://github.com/dotnet/docs/blob/main/docs/fundamentals/code-analysis/style-rules) in the `dotnet/docs` repo. See [Contribute docs for 'IDExxxx' rules](#contribute-docs-for-idexxxx-rules). 21 | 22 | ## Contribute docs for 'CAxxxx' rules 23 | 24 | Please follow the following steps to contribute documentation for code quality analysis rules to the [dotnet/docs](https://github.com/dotnet/docs) repo: 25 | 26 | 1. Determine `Rule ID` and `Category`: Ensure that you know the 'CAxxxx' rule ID and category for the rule to be documented. This means either your CA analyzer has been merged into [dotnet/roslyn-analyzers](https://github.com/dotnet/roslyn-analyzers) repo or you have an open PR with an approved ID and category that has been assigned to the rule. 27 | 2. Add rule doc: 28 | 1. Clone an existing CA rule file under [root](https://github.com/dotnet/docs/blob/main/docs/fundamentals/code-analysis/quality-rules) folder, say `ca1000.md`, and rename it. 29 | 2. Update the content of the file appropriately. 30 | 3. Add an entry for the rule to following tables: 31 | - In [table of contents](https://github.com/dotnet/docs/blob/main/docs/fundamentals/toc.yml) file under the rule category list. For example, for a CA rule with `Performance` category, search for the term `- name: Performance rules` in the file and add an entry to the list. If none exists, create a new category list under `- name: Code quality rules`. 32 | - In [top-level rule index](https://github.com/dotnet/docs/blob/main/docs/fundamentals/code-analysis/quality-rules/index.md) file. 33 | - In `category` based rule index file: 34 | 1. Identify the category based index file under [root](https://github.com/dotnet/docs/blob/main/docs/fundamentals/code-analysis/quality-rules) folder. For example, for a CA rule with `Performance` category, this file is named `performance-warnings.md`. If none exists, create a new category based index file by cloning an existing one. 35 | 2. Add an entry for the rule ID in this file. 36 | 37 | > [!TIP] 38 | > Perform a repo search in the `dotnet/docs` repo for a known, existing CA rule ID to identify potential places that might need an update. For example, see . 39 | 40 | ## Contribute docs for 'IDExxxx' rules 41 | 42 | Please follow the following steps to contribute documentation for code style analysis rules to the [dotnet/docs](https://github.com/dotnet/docs) repo: 43 | 44 | 1. Determine `Rule ID` and code style options, if any: Ensure that you know the 'IDExxxx' rule ID and code style options for the rule to be documented. This means either the IDE analyzer has been merged into the [dotnet/roslyn](https://github.com/dotnet/roslyn) repo or you have an open PR with an approved ID and code style options that have been assigned to the rule. 45 | 2. Determine rule `subcategory`: IDE rules have category `Style`. Identify the rule subcategory by reading through the introductory section of [Code style rules](/dotnet/fundamentals/code-analysis/style-rules/index). Most of the IDE code style rules are under the `Language` subcategory. 46 | 3. Determine rule `preference group`: Identify the `preference group` for the rule by reading through the preferences headers [here](/dotnet/fundamentals/code-analysis/style-rules/language-rules#net-style-rules). 47 | - If the rule has known, associated code style option(s), the preferences group will match the `OptionGroup` specified in the code style option declaration. 48 | - Otherwise, determine if the rule belongs to an existing preference group or needs a new preference group. 49 | 4. Add rule doc: 50 | 1. Clone an existing IDE rule file under [root](https://github.com/dotnet/docs/blob/main/docs/fundamentals/code-analysis/style-rules) folder, say `ide0011.md`, and rename it. 51 | 2. Update the content of the file appropriately. 52 | 5. Add an entry for the IDE rule and/or code style option(s) to the following tables: 53 | - In [table of contents](https://github.com/dotnet/docs/blob/main/docs/fundamentals/toc.yml) file under the rule's sub-category and preferences list. For example, for an IDE code style rule with `Language` subcategory and `Modifier preferences` group, search for the term `- name: Language rules` and a child node `- name: Modifier preferences` in the file and add an entry to the list. If either the subcategory list or the preferences list under the subcategory does not exist, create a new one under `- name: Code style rules`. 54 | - In the [code style option-based index](https://github.com/dotnet/docs/blob/main/docs/fundamentals/code-analysis/style-rules/language-rules.md) file. 55 | - In the [rule ID-based index](https://github.com/dotnet/docs/blob/main/docs/fundamentals/code-analysis/style-rules/index.md) file. 56 | - In `preferences group` based rule index file: 57 | 1. Identify the preferences group based index file under [root](https://github.com/dotnet/docs/blob/main/docs/fundamentals/code-analysis/style-rules) folder. For example, for an IDE rule for `Modifier preferences`, this file is named `modifier-preferences.md`. If none exists, create a new preferences group based index file by cloning an existing one. 58 | 2. Add an entry for the rule ID in this file. 59 | 60 | > [!TIP] 61 | > Perform a repo search in the `dotnet/docs` repo, for a known, existing IDE rule and/or code style option(s) to identify potential places that might need an update. For example, see and . 62 | 63 | ## See also 64 | 65 | - [Contribute to the .NET docs repositories](dotnet-contribute.md) 66 | -------------------------------------------------------------------------------- /Contribute/content/dotnet/dotnet-pr-review.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: .NET docs pull request review process 3 | description: The .NET docs do not have the PR merger webhooks enabled. This article describes the PR process for those repositories 4 | ms.topic: contributor-guide 5 | ms.service: learn 6 | ms.custom: external-contributor-guide 7 | ms.date: 06/24/2020 8 | --- 9 | # Pull request review process for the .NET docs repositories 10 | 11 | Some repositories, including the .NET repositories, don't have the "PR Merger" web hook enabled, which automatically merges minor PRs. This article describes the PR review process for those repositories. The PR review process was designed 12 | with these goals: 13 | 14 | - Publish high-quality content from our team, product team members, and community members. 15 | - Provide timely, actionable feedback to authors in a consistent manner. 16 | - Facilitate discussion between authors and reviewers. 17 | 18 | The processes continue to evolve as teams innovate and as the platform matures. 19 | 20 | ## Reviewers 21 | 22 | One of the content team members reviews every PR. Content team members may request a review from the specific product team members to verify technical accuracy. The content team uses GitHub's Code Ownership feature to automatically request reviews from content team members. As part of this process, a reviewer may tag other team members to review internal PRs. Team members see requested reviews from team members and community members in the same queue. 23 | 24 | Community members can review PRs and provide feedback as well. However, at least one member of the core content team must approve any PR before it is merged. 25 | 26 | ## Review process 27 | 28 | Reviews follow one of the three paths based on the PR: 29 | 30 | - **Small PRs** - Small PRs are single bug fix: typos, broken links, small code changes, or similar changes. 31 | - **Major contributions** - Major contributions are significant edits to an existing article, new articles, or edits to a number of articles. 32 | - **Work in progress** - Authors can can create a PR that is marked as not ready for review yet by opening a *draft* pull request. 33 | 34 | The processing used by the Contributor License Agreement (CLA) bot is a good guideline for the distinction between "small" and "large" contributions. PRs that do not require the CLA to be signed are likely "small." PRs that do require the CLA are likely "large." 35 | 36 | ### Small PRs 37 | 38 | The changes in small PRs are reviewed for accuracy and checked using the build on the review site. Because they are small, these PRs do not trigger a review of the entire article. 39 | 40 | Reviewers may notice other small changes that would improve an article. If those changes are also small, suggest them as review comments. If the suggested changes would trigger a larger review, open an issue and address those later. 41 | 42 | ### Larger changes 43 | 44 | Larger PRs undergo a more thorough review. The following are all checked: 45 | 46 | - Sample code must be included in the PR, in source and as a downloadable zip file. 47 | - Sample code compiles and runs correctly. 48 | - The article clearly describes the goals for the reader, and those goals are met. 49 | - The article meets [style and grammar guidelines](dotnet-style-guide.md) and follows our [voice and tone principles](dotnet-voice-tone.md). 50 | - All links should resolve correctly. 51 | 52 | Content team members will review the PR and submit the review with comments. If only minor changes are requested, team members may "approve" the PR with the feedback. The author can then address the feedback and merge the PR. Most reviews will request changes and when those changes are made, the reviewer will review again. 53 | 54 | If the edits require a technical review, the content team reviewer will request a review from the appropriate product team member. 55 | 56 | ### Review draft pull requests 57 | 58 | You may want feedback earlier in the process. Open a draft PR and add a comment that requests an early review. These early reviews focus on the structure of the article: the outline, the overall content, and the samples. These reviews do not include a thorough check for grammar and correct links. 59 | 60 | ## Explain suggestions 61 | 62 | GitHub lets you enter comments in triple-back-tick blocks of type `suggestion` that are displayed as a diff and can be merged by clicking a button. On short lines, GitHub does a good job of highlighting the changes. On longer lines, such as a long paragraph in one line of text, GitHub doesn't highlight the changes. When entering a suggestion for a long line, notice whether your changes are clearly highlighted. If the changes aren't highlighted, include comments outside the suggestion block explaining what you changed. Without an explanation it's often time-consuming for subsequent reviewers or the PR author to figure out what the changes are. 63 | 64 | ## Respond to reviews 65 | 66 | The author updates the PR to respond to comments. If the author disagrees with the comment, or addresses the comment in a different PR, the author adds a comment explaining their change. 67 | 68 | The author @-mentions the original reviewer in a comment to request a new review. 69 | 70 | ## Response time expectations 71 | 72 | Content team members will typically review new PRs in under two business days. 73 | 74 | Once a review has been submitted, authors should try to respond to comments in a week or less. Volunteers may not be able to meet these expectations because of other commitments. In those cases, team members ask if the community author will update the PR. If not, the team member updates and merges the PR for them. 75 | -------------------------------------------------------------------------------- /Contribute/content/dotnet/dotnet-voice-tone.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Voice and tone guidelines for .NET docs contributions 3 | description: Learn our voice and tone guidelines through examples of our styles compared to examples that don't follow our guidelines. 4 | ms.topic: contributor-guide 5 | ms.service: learn 6 | ms.custom: external-contributor-guide 7 | ms.date: 11/07/2018 8 | --- 9 | # Voice and tone guidelines 10 | 11 | A wide variety of people including IT Pros and developers read the .NET docs both to learn .NET and to use it in their regular work. Your goal is to create great documentation that helps the reader on their journey. Our guidelines help with that. Our style guide contains the following recommendations: 12 | 13 | ## Use a conversational tone 14 | 15 | The following paragraph is written in a conversational style. The one that follows it is in a more academic style. 16 | 17 | ### Appropriate style 18 | 19 | We want our documentation to have a conversational tone. You should feel as though you are having a conversation with the author as you read any of our tutorials or explanations. For you, the experience should be informal, conversational, and informative. Readers should feel as though they are listening to the author explain the concepts to them. 20 | 21 | ### Inappropriate style 22 | 23 | One might see the contrast between a conversational style and the style one finds with more academic treatments of technical topics. Those resources are very useful, but the authors have written those articles in a very different style than our documentation. When one reads an academic journal, one finds a very different tone and a very different style of writing. One feels that they are reading a dry account of a very dry topic. 24 | 25 | ## Write in second person 26 | 27 | The following paragraph uses second person. The one that follows it uses third person. Please write in second person. 28 | 29 | ### Appropriate style 30 | 31 | Write your articles as though you are speaking directly to the reader. Use second person often (as in these two sentences). 2nd person doesn't always mean using the word 'you'. Write directly to the reader. Write imperative sentences. Tell your reader what you want them to learn. 32 | 33 | ### Inappropriate style 34 | 35 | An author could also choose to write in third person. In that model, an author must find some pronoun or noun to use when referring to the reader. A reader might often find this third person style less engaging and less enjoyable to read. 36 | 37 | ## Use active voice 38 | 39 | Write your articles in active voice. Active voice means that the subject of the sentence performs the action (verb) of that sentence. It contrasts with passive voice, where the sentence is arranged 40 | such that the subject of the sentence is acted upon. Contrast these two examples: 41 | 42 | >The compiler transformed source code into an executable. 43 | 44 | >The source code was transformed into an executable by the compiler. 45 | 46 | The first sentence uses active voice. The second sentence was written in passive voice. (Those two sentences provide another example of each style). 47 | 48 | We recommend active voice because it is more readable. Passive voice can be more difficult to read. 49 | 50 | ## Write for readers who may have a limited vocabulary 51 | 52 | You are reaching an international audience with your articles. Many of your readers are not native English speakers and may not have the English vocabulary you have. 53 | 54 | However, you are still writing for technical professionals. You can assume that your readers have programming knowledge and the specific vocabulary for programming terms. Object Oriented Programming, Class and Object, Function and Method are familiar terms. However, not everyone reading your articles has a formal computer science degree. Terms like 'idempotent' probably need to be defined if you use it, for example: 55 | 56 | > The `Close()` method is idempotent, meaning that you can call it multiple times and the effect is the same as if you called it once. 57 | 58 | ## Avoid future tense 59 | 60 | In some non-English languages the concept of future tense is not the same as English. Using future tense can make your documents harder to read. Additionally, when using the future tense, the obvious question is when. So if you say 'Learning PowerShell will be good for you" - the obvious question for the reader is when will it be good? Instead, just say "Learning PowerShell is good for you". 61 | 62 | ## What is it - so what? 63 | 64 | Whenever you introduce a new concept to the reader, define the concept and only then explain why it's useful. It's important for reader to understand what something is before they can understand the benefits (or otherwise). 65 | -------------------------------------------------------------------------------- /Contribute/content/dotnet/labels-projects.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Labels, projects, and milestones roadmap 3 | description: This article explains how labels, projects, and milestones are used in the dotnet/docs repository. 4 | ms.topic: contributor-guide 5 | ms.service: learn 6 | ms.custom: external-contributor-guide 7 | ms.date: 02/10/2021 8 | --- 9 | 10 | # Labels, projects, and milestones roadmap 11 | 12 | The .NET docs team makes extensive use of [GitHub labels](https://github.com/dotnet/docs/labels) to organize our work. By filtering on combinations of labels, we can quickly focus on sections of interest on the [.NET docs website](/dotnet). For example, we could filter to all of the open issues on the architecture guides with a query to [is:issue is:open label:"dotnet-architecture/prod"](https://github.com/dotnet/docs/labels/dotnet-architecture%2Fprod). 13 | 14 | We use [GitHub projects](https://github.com/dotnet/docs/projects) to organize sprints and other goal-oriented epics. We also use [GitHub milestones](https://github.com/dotnet/docs/milestones) to track work. It is best to think of projects for planning (issues), and milestones for work (pull requests). 15 | 16 | This roadmap explains how we use these organizational tools and has links to handy filters we use to find areas of interest. 17 | 18 | ## Labels 19 | 20 | If this is your first experience contributing to [dotnet/docs](https://github.com/dotnet/docs), start with the [up-for-grabs](https://github.com/dotnet/docs/labels/up-for-grabs) issues. These are issues that have a more focused scope. They are a great way to make your first contribution. From the up-for-grabs view, you can further filter issues based on areas and priority. We've identified good issues for beginners with the [good-first-issue](https://github.com/dotnet/docs/labels/good-first-issue) if you want to try a smaller first contribution. 21 | 22 | We use labels to classify issues in many different ways: 23 | 24 | - [.NET Guides](#find-issues-for-a-single-net-guide) and [sections of a guide](#find-issues-for-one-section-of-a-guide). 25 | - [Target release](#releases) 26 | - [Priority](#priority) 27 | 28 | You can combine a label from each set (guide, release, priority) to create a narrow focus to find issues you want to work on. 29 | 30 | ### Find issues for a single .NET guide 31 | 32 | We use labels for each of the architecture e-books and for each .NET Guide. All ebooks are noted with the [dotnet-architecture/prod](https://github.com/dotnet/docs/labels/dotnet-architecture%2Fprod) label. Each book has a unique label that ends with `/tech`. 33 | 34 | Each .NET Guide is noted with the [`/prod`](https://github.com/dotnet/docs/labels?q=prod) suffix and has a blue-gray background. Here are current issues filtered for each of the .NET guides. 35 | 36 | - [.NET Guide - `dotnet/prod`](https://github.com/dotnet/docs/labels/dotnet%2Fprod) 37 | - [.NET Fundamentals Guide (formerly .NET Standard Guide) - `dotnet-fundamentals/prod`](https://github.com/dotnet/docs/labels/dotnet-fundamentals%2Fprod) 38 | - [.NET Fundamentals Guide (formerly .NET Core Guide) - `dotnet-core/prod`](https://github.com/dotnet/docs/labels/dotnet-core%2Fprod) 39 | - [.NET Framework Guide - `dotnet-framework/prod`](https://github.com/dotnet/docs/labels/dotnet-framework%2Fprod) 40 | - [API Reference - `dotnet-api/prod`](https://github.com/dotnet/docs/labels/dotnet-api%2Fprod) 41 | - [C# Guide - `dotnet-csharp/prod`](https://github.com/dotnet/docs/labels/dotnet-csharp%2Fprod) 42 | - [F# Guide- `dotnet-fsharp/prod`](https://github.com/dotnet/docs/labels/dotnet-fsharp%2Fprod) 43 | - [Visual Basic Guide - `dotnet-visualbasic/prod](https://github.com/dotnet/docs/labels/dotnet-visualbasic%2Fprod) 44 | - [ML.NET Guide - `dotnet-ml/prod`](https://github.com/dotnet/docs/labels/dotnet-ml%2Fprod) 45 | - [Azure .NET SDK - `azure-dotnet/prod`](https://github.com/dotnet/docs/labels/azure-dotnet%2Fprod) 46 | - [.NET for Apache Spark Guide - `dotnet-spark/prod`](https://github.com/dotnet/docs/labels/dotnet-spark%2Fprod) 47 | - [.NET Desktop Guide - `dotnet-desktop/prod`](https://github.com/dotnet/docs/labels/dotnet-desktop%2Fprod) 48 | 49 | Other product labels are defined for areas that cross repositories. 50 | 51 | #### Find issues for one section of a guide 52 | 53 | The .NET guides are large, so these labels further limit the scope by a section of a guide. Each .NET Guide subarea is noted with the [`/tech`](https://github.com/dotnet/docs/labels?q=tech) suffix and has a light blue background. Many of these labels apply to multiple guides, while others are in only one guide. After filtering on an area, add one of these labels to further limit the scope of issues. 54 | 55 | ### Releases 56 | 57 | ![:checkered_flag: Release: on dark yellow](./media/labels-projects/release.png "Prefix for release labels") 58 | 59 | Issues tagged for a specific release are noted with the [`:checkered_flag: Release:`](https://github.com/dotnet/docs/labels?q=%3Acheckered_flag%3A+Release) prefix and have a dark yellow background. 60 | 61 | ### Priority 62 | 63 | Priority labels are all `Pri` followed by a single digit. Lower numbers are higher priority: 64 | 65 | - Pri0 - Critical priority 66 | 67 | Security issue or legally required for compliance. We drop everything else to fix. 68 | 69 | - Pri1 - High priority 70 | 71 | Essential for common scenarios. Or highly visible error on high page view article. We do these before P2 or P3 work. 72 | 73 | - Pri2 - Medium priority 74 | 75 | Helpful for common scenarios but not blocking. We do these if quick and easy, or fit them in while addressing a P1 issue in the same article. 76 | 77 | - Pri3 - Low priority 78 | 79 | Helpful for edge cases, trivial corrections for common scenarios, low page view article, or deprecated technology. Not worth our time but up for grabs for community contribution. A P3 issue may be closed if not addressed after two months. 80 | 81 | ### What about the other labels 82 | 83 | There are many other labels used by the content teams to manage different classifications of issues. If you're not on the content team, you can ignore these other labels. 84 | 85 | ## Projects 86 | 87 | Projects are intended for planning purposes, where prioritized work is automated through a Kanban board. Projects should only ever contain GitHub issues, _not_ pull requests. Projects differ from milestones, in that milestones only contain pull requests. 88 | 89 | We use projects in two ways: 90 | 91 | - `Month YYYY` project types: These are Kanban boards for each month's working plan. 92 | - Examples, [July 2020](https://github.com/dotnet/docs/projects/103), [August 2020](https://github.com/dotnet/docs/projects/117), and so on. 93 | - Long-running epics: These are used to organize tasks toward a goal when the work will occur over several months. 94 | - Examples: [.NET 5 Wave - Reorganization](https://github.com/dotnet/docs/projects/105), [.NET Languages (.NET 5 wave) 95 | ](https://github.com/dotnet/docs/projects/106), and so on. 96 | 97 | ## Milestones 98 | 99 | Milestones typically follow the same naming convention of projects `Month YYYY`, but they're different from projects. We use milestones to track completed work. Milestones should _not_ contain issues (potential work), but rather exclusively contain pull requests. The current milestone is automatically applied to new pull requests. 100 | -------------------------------------------------------------------------------- /Contribute/content/dotnet/media/labels-projects/release.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/dotnet/media/labels-projects/release.png -------------------------------------------------------------------------------- /Contribute/content/dotnet/media/labels-projects/technology.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/dotnet/media/labels-projects/technology.png -------------------------------------------------------------------------------- /Contribute/content/dotnet/net-core-5-naming.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: "How to refer to .NET in docs" 3 | description: "Learn how to refer to .NET Framework, .NET Core, .NET 5, and later versions in docs." 4 | ms.topic: contributor-guide 5 | ms.service: learn 6 | ms.custom: external-contributor-guide 7 | ms.date: 01/28/2021 8 | --- 9 | # How to refer to .NET in docs 10 | 11 | This article is mostly concerned with naming for .NET Core and .NET 5 and later versions. For .NET Framework, it should be referred to as ".NET Framework" and not "the .NET Framework". 12 | 13 | ## Recommended terminology 14 | 15 | **In doc title and first heading (h1):** 16 | 17 | - ".NET" (without mention of 5 or Core) 18 | 19 | **First reference in article text:** 20 | 21 | - ".NET" for docs about Core/5+ that present it to people new to .NET. 22 | - ".NET 5 (and .NET Core) and later versions" if needed to emphasize Core/5+ as a specific .NET implementation. 23 | 24 | **Subsequent references:** 25 | 26 | - ".NET" for docs that present Core/5+ to people new to .NET or where the reference to Core/5+ is clear in context. 27 | - ".NET 5 and later versions" where necessary to differentiate Core/5+ from other .NET implementations. 28 | 29 | **Notes:** 30 | 31 | - Other options we considered: 32 | - ".NET 5 (and .NET Core 2.1/3.1) and later versions" – the Core version numbers seem unnecessary and make the phrase longer than it needs to be. 33 | - ".NET 5 and later versions (formerly known as .NET Core)" -- could lead to confusion in that "5 and later" seems to exclude 2.1-3.1. 34 | - ".NET 5 and later versions (including .NET Core 2.1-3.1)" – similar issue in that 2.1-3.1 sounds they should be among the "later versions" 35 | - ".NET 5+" is a shorter alternative to ".NET 5 and later versions", but there are concerns that it would not be universally understood. 36 | - ".NET 5 and later versions" will remain an accurate description after version 6 and later versions are released. But eventually ".NET" will be understood to mean 5+ and we may be able to eliminate "5 and later versions" in some contexts. 37 | 38 | ## Examples 39 | 40 | ### [Changes that affect compatibility](/dotnet/core/compatibility/) 41 | 42 | | Before .NET 5 | Current recommendation | 43 | | --- | --- | 44 | | Throughout its history, .NET has attempted to maintain a high level of compatibility from version to version and across flavors of .NET. This continues to be true for .NET Core. Although .NET Core can be considered as a new technology that is independent of the .NET Framework, two major factors limit the ability of .NET Core to diverge from .NET Framework: | Throughout its history, .NET has attempted to maintain a high level of compatibility from version to version and across implementations of .NET. Although .NET 5 (and .NET Core) and later versions can be considered as a new technology compared to .NET Framework, two major factors limit the ability of this implementation of .NET to diverge from .NET Framework: | 45 | | .NET Standard library projects allow developers to create libraries that target common APIs shared by .NET Core and .NET Framework | .NET Standard library projects allow developers to create libraries that target common APIs shared by .NET Framework and .NET 5 (and .NET Core) and later versions. | 46 | | This article is not a complete list of breaking changes between .NET Framework and .NET Core. | This article is not a complete list of breaking changes in .NET 5 (and .NET Core) and later versions, compared to .NET Framework. | 47 | | The following APIs will always throw a `PlatformNotSupportedException` on .NET Core. | The following APIs will always throw a `PlatformNotSupportedException` on .NET 5 (and .NET Core) and later versions. | 48 | 49 | ### [Install .NET on Windows](/dotnet/core/install/windows) 50 | 51 | | Before .NET 5 | Current recommendation | 52 | | --- | --- | 53 | | Title/h1: Install .NET Core on Windows | Title/h1: Install .NET on Windows | 54 | | In this article, you'll learn how to install .NET Core on Windows. .NET Core is made up of the runtime and the SDK. The runtime is used to run a .NET Core app and may or may not be included with the app. The SDK is used to create .NET Core apps and libraries. The .NET Core runtime is always installed with the SDK. | In this article, you'll learn how to install .NET 5 (and .NET Core) and later versions on Windows. .NET is made up of the runtime and the SDK. The runtime is used to run a .NET app and may or may not be included with the app. The SDK is used to create .NET apps and libraries. The .NET runtime is always installed with the SDK. | 55 | 56 | ### [How to check that .NET is already installed](/dotnet/core/install/how-to-detect-installed-versions) 57 | 58 | | Before .NET 5 | Current recommendation | 59 | | --- | --- | 60 | | Title/h1: How to check that .NET Core is already installed | Title/h1: How to check that .NET is already installed | 61 | | This article teaches you how to check which versions of the .NET Core runtime and SDK are installed on your computer. .NET core may have already been installed if you have an integrated development environment, such as Visual Studio or Visual Studio for Mac. | This article teaches you how to check which versions of the runtime and SDK for .NET 5 (and .NET Core) and later versions are installed on your computer. The runtime and SDK may have already been installed if you have an integrated development environment, such as Visual Studio or Visual Studio for Mac. | 62 | 63 | ### [Tutorial: Create a .NET console application using Visual Studio](/dotnet/core/tutorials/with-visual-studio) 64 | 65 | | Before .NET 5 | Current recommendation | 66 | | --- | --- | 67 | | Title/h1: Tutorial: Create a .NET Core console application using Visual Studio | Title/h1: Tutorial: Create a .NET console application using Visual Studio | 68 | | This tutorial shows how to create and run a .NET Core console application in Visual Studio 2019. | This tutorial shows how to create and run a .NET console application in Visual Studio 2019. | 69 | | Prerequisites:Visual Studio 2019 version 16.6 or a later version with the .NET Core cross-platform development workload installed. The .NET Core 3.1 SDK is automatically installed when you select this workload. | PrerequisitesVisual Studio 2019 version 16.6 or a later version with the .NET cross-platform development workload installed. The .NET SDK is automatically installed when you select this workload. | 70 | 71 | 72 | ### [Tutorial: Create an item template](/dotnet/core/tutorials/cli-templates-create-item-template) 73 | 74 | | Before .NET 5 | Current recommendation | 75 | | --- | --- | 76 | | Title/h1:Tutorial: Create an item template | Title/h1:Tutorial: Create an item template | 77 | | With .NET Core, you can create and deploy templates that generate projects, files, even resources. | With .NET, you can create and deploy templates that generate projects, files, even resources. | 78 | | Prerequisites: .NET Core 2.2 SDK or a later version. | Prerequisites: .NET Core 2.2 SDK or a later version (including .NET 5 and later versions). | 79 | 80 | ### [.NET SDK overview](/dotnet/core/sdk) 81 | 82 | | Before .NET 5 | Current recommendation | 83 | | --- | --- | 84 | | Title/h1: .NET Core SDK overview | Title/h1: .NET SDK overview | 85 | | "the SDK" in the text | no change | 86 | 87 | ### [.NET CLI overview](/dotnet/core/tools) 88 | 89 | | Before .NET 5 | Current recommendation | 90 | | --- | --- | 91 | | Title/h1: .NET Core CLI overview | Title/h1: .NET CLI overview | 92 | | The .NET Core command-line interface (CLI) is a cross-platform toolchain for developing, building, running, and publishing .NET Core applications. | The .NET command-line interface (CLI) is a cross-platform toolchain for developing, building, running, and publishing .NET applications. | 93 | 94 | ### [.NET application publishing overview](/dotnet/core/deploying/) 95 | 96 | | Before .NET 5 | Current recommendation | 97 | | --- | --- | 98 | | Title/h1:.NET Core application publishing overview | Title/h1:.NET application publishing overview | 99 | | Applications you create with .NET Core can be published in two different modes, and the mode affects how a user runs your app. | Applications you create with .NET 5 (and .NET Core) and later versions can be published in two different modes, and the mode affects how a user runs your app. | 100 | | Publishing your app as self-contained produces an application that includes the .NET Core runtime and libraries, and your application and its dependencies. Users of the application can run it on a machine that doesn't have the .NET Core runtime installed. | Publishing your app as self-contained produces an application that includes the .NET runtime and libraries, and your application and its dependencies. Users of the application can run it on a machine that doesn't have the .NET runtime installed. | 101 | 102 | ### [dotnet new](/dotnet/core/tools/dotnet-new) 103 | 104 | | Before .NET 5 | Current recommendation | 105 | | --- | --- | 106 | | **This article applies to:** ✔️ .NET Core 2.1 SDK and later versions | **This article applies to:** ✔️ .NET Core 2.1 SDK and later versions (including .NET 5 SDK and later versions) | 107 | | **`--dry-run`** Displays a summary of what would happen if the given command were run if it would result in a template creation. Available since .NET Core 2.2 SDK. | no change (keep "Available since .NET Core 2.2 SDK") | 108 | 109 | ### "Applies to" link text in API ref docs 110 | 111 | | Before .NET 5 | Current recommendation | 112 | | --- | --- | 113 | | \.NET Core only: In all cases\ | \.NET 5 (and .NET Core) and later versions: In all cases.\ | 114 | -------------------------------------------------------------------------------- /Contribute/content/get-started-setup-tools.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Install content-authoring tools 3 | description: This article helps you download and install the client tools you'll need for using Git and editing Markdown files to edit documentation on Microsoft Learn. 4 | zone_pivot_groups: contribute-tools-zone-pivots-os 5 | ms.topic: contributor-guide 6 | ms.service: learn 7 | ms.custom: external-contributor-guide 8 | author: carlyrevier 9 | ms.author: cahublou 10 | ms.date: 09/27/2023 11 | --- 12 | 13 | # Install content-authoring tools 14 | 15 | This article describes how to install the recommended tools you need to make efficient in-depth or large contributions to Microsoft Learn. Examples of major updates include: 16 | 17 | - Lengthy revisions to multiple articles 18 | - Creating a new article 19 | - Work for which you'd want to use the available Visual Studio Code extensions, like [Learn Authoring Pack](how-to-write-docs-auth-pack.md). 20 | 21 | > [!IMPORTANT] 22 | > If you're making only minor changes, you *don't* need to complete the steps in this article. See [Edit in the browser](how-to-write-quick-edits.md) to learn how to make quick edits without installing any tools. 23 | 24 | Contributors who'll be making major changes are encouraged to complete these steps. Even if you have write permissions in the main repository, *we highly recommend (and this guide assumes) that you fork and clone the repository* and store your proposed changes in your fork. 25 | 26 | In this article, you'll: 27 | 28 | > [!div class="checklist"] 29 | > * Install [Git](https://git-scm.com/) 30 | > * Install [Visual Studio Code](https://code.visualstudio.com/) 31 | > * Install the [Learn Authoring Pack](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-authoring-pack) 32 | 33 | ::: zone pivot="windows-os-pivot-selection" 34 | 35 | ## Install Git client tools for Windows 36 | 37 | This installation includes the Git version control system and Git Bash, the command-line app that you use to interact with your local Git repository. 38 | 39 | 1. Download [Git for Windows](https://git-scm.com/download/win). 40 | 41 | 1. Run the downloaded executable (.EXE) file and follow the prompts to install. Select **Next** at each prompt to accept all default settings. 42 | 43 | 1. Select a code editor, when prompted. The default code editor is Vim. 44 | 45 | 1. Select **Finish** to complete the installation. 46 | 47 | After installing Git for Windows, configure your Git name and your email address. 48 | 49 | ::: zone-end 50 | 51 | ::: zone pivot="mac-os-pivot-selection" 52 | 53 | ## Install Git client tools for Mac and Linux 54 | 55 | - Git for Mac is provided as part of the Xcode Command Line Tools. Simply run `git` from the command line. You will be prompted to install the command line tools if needed. You can also download [Git for Mac](https://git-scm.com/download/mac) from the Software Freedom Conservancy. 56 | - [Git for Linux and Unix](https://git-scm.com/download/linux) 57 | 58 | Follow the instructions for your chosen client for installation and configuration. 59 | 60 | ::: zone-end 61 | 62 | ## Install Visual Studio Code 63 | 64 | [Visual Studio Code](https://code.visualstudio.com/) is a lightweight editor that works on Windows, Linux, and Mac. It includes Git integration and support for extensions. 65 | 66 | Download and install Visual Studio Code for your operating system: 67 | 68 | - [Windows](https://code.visualstudio.com/docs/setup/windows). 69 | - [Mac](https://code.visualstudio.com/docs/setup/mac) 70 | - [Linux](https://code.visualstudio.com/docs/setup/linux) 71 | 72 | During installation, accept all default settings. 73 | 74 | > [!TIP] 75 | > To launch VS Code and open the current folder, run the command `code .` in the command line or Bash shell. If the current folder is part of a local Git repo, the GitHub integration appears in Visual Studio Code automatically. 76 | 77 | ## Install Learn Authoring Pack 78 | 79 | The Learn Authoring Pack for Visual Studio Code includes basic Markdown authoring assistance, page previews, support for Markdown templates, markdownlint, and Code Spell Checker. These features ease and streamline the contribution process. As such, we consider the Learn Authoring Pack a **required** extension for contributors. 80 | 81 | To install the Learn Authoring Pack, choose **Install** from the [Learn Authoring Pack page](https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-authoring-pack) in the VS Code Marketplace. 82 | 83 | To use the Learn Authoring Pack functionality, press `Alt+M` in Visual Studio Code. To configure a toolbar to show the functions available, edit the Visual Studio Code settings (Control+comma), and add user setting `"markdown.showToolbar": true`. 84 | 85 | For more information, see [Learn Authoring Pack for Visual Studio Code](how-to-write-docs-auth-pack.md). 86 | 87 | ## Understand Markdown editors 88 | 89 | Markdown is a lightweight markup language used to author the content. [Visual Studio Code](https://code.visualstudio.com/) is the preferred tool for editing Markdown at Microsoft. Other Markdown editing tools are available. The [Markdown Reference](markdown-reference.md) article covers Markdown basics and the features supported by the `learn.microsoft.com` website. 90 | 91 | ## Next steps 92 | 93 | Now you're ready to [Set up a local Git repository](get-started-setup-local.md). 94 | -------------------------------------------------------------------------------- /Contribute/content/hacktoberfest.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Hacktoberfest and Microsoft Learn 3 | description: Learn how to discover which Microsoft Learn repositories participate in Hacktoberfest, how to contribute, and what you can expect as a contributor. 4 | 5 | author: IEvangelist 6 | ms.author: dapine 7 | ms.date: 09/26/2023 8 | ms.topic: contributor-guide 9 | ms.service: learn 10 | ms.custom: external-contributor-guide 11 | --- 12 | 13 | # Hacktoberfest and Microsoft Learn 14 | 15 | Hacktoberfest is an annual worldwide event held during the month of October. The event encourages open source developers to contribute to repositories through pull requests (PR). GitHub hosts many open source repositories that contribute to [Microsoft Learn](/) content. Some of the repositories actively participate in the Hacktoberfest event. In this article, you'll learn how to discover which repos are accepting PRs, and what you can expect as a contributor. 16 | 17 | ## Find a repo 18 | 19 | To discover if a Microsoft Learn repo is participating in Hacktoberfest, you'll see the **hacktoberfest** topic on the project. 20 | 21 | :::image type="content" source="media/hacktoberfest/github-topic.png" lightbox="media/hacktoberfest/github-topic.png" alt-text="GitHub .NET docs repository with hacktoberfest topic."::: 22 | 23 | To filter all Microsoft Learn and .NET repos that have the **hacktoberfest** topic, see [GitHub Topics: Hacktoberfest](https://github.com/topics/hacktoberfest?q=org%3AMicrosoftDocs+org%3Adotnet). 24 | 25 | Alternatively, a repository may choose to use the `Hacktoberfest` label instead. This label is convenient for filtering issues. For more information, see [Filtering issues and pull requests by labels](https://docs.github.com/github/administering-a-repository/finding-information-in-a-repository/filtering-issues-and-pull-requests-by-labels). 26 | 27 | > [!TIP] 28 | > If you're a repo admin and you want to allow your repo to participate in Hacktoberfest, add the `hacktoberfest` topic to the repo. For more information, see [Classifying your repository with topics](https://docs.github.com/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). 29 | 30 | ## Contribute 31 | 32 | To contribute to an open source repo, you must first configure your account to contribute to Microsoft Learn. If you have never completed this process, start by [signing up for a GitHub account](./get-started-setup-github.md). You must also register a profile to track your efforts. See [Hacktoberfest](https://hacktoberfest.com/). 33 | 34 | Once your account is configured, start by reading through and adhering to the _CONTRIBUTING.md_ file at the root of the repository you want to contribute to. These files serve as a guide when contributing. Here are a few example contributor guides from some popular Microsoft Learn repos: 35 | 36 | - [Contribute to the .NET documentation](./dotnet/dotnet-contribute.md) 37 | - [Contribute to Microsoft Azure documentation](https://github.com/MicrosoftDocs/azure-docs/blob/main/CONTRIBUTING.md) 38 | 39 | In addition to the contributing Markdown file, if a repository has a *CODE_OF_CONDUCT.md* file, it's a requirement to adhere to the expected behavior in the community. Again, here are a few common examples: 40 | 41 | - [.NET Docs: Code of Conduct](https://github.com/dotnet/docs/blob/main/CODE_OF_CONDUCT.md) 42 | - [Azure Docs: Code of Conduct](https://github.com/MicrosoftDocs/azure-docs/blob/main/CODE_OF_CONDUCT.md) 43 | 44 | For more information, see [Hacktoberfest: Participation](https://hacktoberfest.com/participation). 45 | 46 | ### Choose an issue 47 | 48 | To find an issue to work on in a participating repository, filter the issues for either the `up-for-grabs` or `help-wanted` GitHub labels. While you can address other issues, it's easier to focus on issues that have a well-defined scope and are self-contained. In addition to the Microsoft Learn repos, you can use the following sites for beginners: 49 | 50 | - [Awesome for beginners](https://github.com/mungell/awesome-for-beginners) 51 | - [Up for grabs](https://up-for-grabs.net) 52 | - [First timers only](https://www.firsttimersonly.com) 53 | 54 | For more information, see [Hacktoberfest: Beginners](https://hacktoberfest.com/participation/#beginner-resources). 55 | 56 | ### Quality expectations 57 | 58 | To have a successful contribution to an open source Microsoft Learn repository, [create a meaningful and impactful PR](#open-a-pr). The following examples from the official Hacktoberfest site are considered ***low-quality contributions***: 59 | 60 | - PRs that are automated (for example, scripted opening PRs to remove whitespace, fix typos, or optimize images). 61 | - PRs that are disruptive (for example, taking someone else's branch or commits and making a PR). 62 | - PRs that are regarded by a project maintainer as a hindrance vs. helping. 63 | - A submission that's clearly an attempt to simply +1 your PR count for October. 64 | 65 | Finally, one PR to fix a typo is fine, but five PRs to remove a stray whitespace are not. 66 | 67 | For more information, see [Hacktoberfest: Values](https://hacktoberfest.com/participation/#values). 68 | 69 | ### Open a PR 70 | 71 | A *PR* provides a convenient way for a contributor to propose a set of changes. When opening a PR, specify in the original comment that it's intended to contribute to *hacktoberfest*. Successful PRs have these common characteristics: 72 | 73 | - The PR adds value. 74 | - The contributor is receptive to feedback. 75 | - The intended changes are well articulated. 76 | - The changes are related to an existing issue. 77 | 78 | If you're proposing a PR without a corresponding issue, create an issue first. For more information, see [GitHub: About pull requests](https://docs.github.com/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). 79 | 80 | ## See also 81 | 82 | - [GitHub account setup](get-started-setup-github.md) 83 | - [Git and GitHub essentials for Microsoft Learn documentation](git-github-fundamentals.md) 84 | - [Official Hacktoberfest site](https://hacktoberfest.com) 85 | -------------------------------------------------------------------------------- /Contribute/content/how-to-create-github-issues.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Create GitHub issues for open-source products 3 | description: Learn how to create issues in GitHub to alert the content team when you spot errors in Microsoft Learn documentation for open-source products. 4 | author: carlyrevier 5 | ms.author: cahublou 6 | ms.date: 02/23/2024 7 | ms.topic: contributor-guide 8 | ms.service: learn 9 | ms.custom: external-contributor-guide 10 | --- 11 | 12 | # Create GitHub issues for open-source products 13 | 14 | This article teaches you how to create a GitHub issue for Microsoft Learn documentation related to open-source products. It also teaches you how to peruse other users' issues and either add your own comments to them or open a pull request (PR) to address them. 15 | 16 | Our open-source product documentation is a continuous work in progress. Receiving good GitHub issues from contributors helps us focus our efforts on the highest priorities for the community. 17 | 18 | Of course, if you know how to fix an issue, we invite you to [make the changes yourself](how-to-write-quick-edits.md), instead of opening an issue. 19 | 20 | > [!NOTE] 21 | > Only open-source products using the open-source feedback experience accept GitHub issues. For more information and a list of participating repositories, see [Use the open-source experience](provide-feedback.md#use-the-open-source-experience). To learn about how to provide non-GitHub feedback across the Microsoft Learn platform, see [Provide feedback on Microsoft Learn](provide-feedback.md). 22 | 23 | ## Prerequisites 24 | 25 | - [Create a GitHub account](index.md#create-a-github-account), if you don't have one. 26 | 27 | ## Create an issue 28 | 29 | 1. Navigate to the article you want to comment on. 30 | 1. Scroll to the bottom of the article, where you'll see options for submitting feedback. Select **Open a documentation issue** to create a new issue. This feedback is specific to the content and is tracked as an issue in GitHub. 31 | 32 | ![Screenshot of the bottom of an article, showing the feedback options.](media/how-to-create-github-issues/feedback-links.png) 33 | 34 | Optionally, select **Provide product feedback** to go to a destination (for example, a feedback portal, GitHub, an email address) where you can provide feedback on the product itself. This feedback is independent of the content and has no relationship back to the original article. 35 | 36 | 1. The system opens a new issue for you in the GitHub repository that stores the content for the article you're viewing. Add a title and a description; all other fields should populate for you automatically. When you're done, select **Submit new issue**. 37 | 38 | :::image type="content" source="media/how-to-create-github-issues/github-issue.png" alt-text="Screenshot of the new-issue form in GitHub."::: 39 | 40 | The more detail you provide, the more helpful the issue is. Tell us what information you sought or the search terms you used to get to this article. If you can't get started, tell us how you want to start exploring unfamiliar technology. You can also add screenshots or files to help us understand your issue. 41 | 42 | That's it! Your issue is now added to the Issues queue. Issues start the conversation about what's needed. The content team will respond to these issues with ideas for what we can add and ask for your opinions. 43 | 44 | ## Comment on an issue 45 | 46 | You can comment on any issue in a repository that supports GitHub issues. You can also add your own comments to an issue you've created. 47 | 48 | 1. Find the issue you want to comment on. In your browser, navigate to the GitHub repository you want to look at issues for. Choose the **Issues** tab to see the open issues for that repo. If the repo has a lot of issues, use the **Filters** bar to filter by label, author, and more. Or use the **Search** bar to look for specific queries. Once you find an issue that appeals to you, select it to open it. 49 | 50 | Only open-source products using the open-source feedback experience accept GitHub issues. For more information and a list of participating repositories, see [Use the open-source experience](provide-feedback.md#use-the-open-source-experience). 51 | 52 | 1. Read the issue and any comments that have already been added by others. If you want to add a comment, scroll to the bottom of the issue and enter your comment in the **Leave a comment** box. When you're done, select **Comment**. 53 | 54 | :::image type="content" source="media/how-to-create-github-issues/comment-issue.png" alt-text="Screenshot of a GitHub issue with a comment box at the bottom."::: 55 | 56 | ## Open a pull request to address issues 57 | 58 | As you browse issues, you may find one that you know how to fix. If so, you're welcome to open a PR to address the issue. For more information, see [Edit documentation in the browser](how-to-write-quick-edits.md). 59 | 60 | Once you've opened a PR to address the issue, return to the issue and add a comment that links to your PR. This helps us track the issue and the PR together. Use the pound sign (#) followed by the PR number to link to the PR. For example, if your PR number is 4210, you'd enter `#4210` in your comment. 61 | 62 | :::image type="content" source="media/how-to-create-github-issues/pr-open-issue.png" alt-text="Screenshot of the GitHub issue comment box with a link to a PR."::: 63 | -------------------------------------------------------------------------------- /Contribute/content/how-to-review-pull-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Review open pull requests in GitHub 3 | description: Learn how to provide your expertise on GitHub pull requests related to Microsoft Learn documentation. 4 | author: carlyrevier 5 | ms.author: cahublou 6 | ms.date: 08/28/2023 7 | ms.topic: contributor-guide 8 | ms.prod: non-product-specific 9 | ms.custom: external-contributor-guide 10 | --- 11 | 12 | # Review open pull requests in GitHub 13 | 14 | This article explains how to contribute to Microsoft Learn by reviewing pull requests (PRs) and adding your comments. You can read new topics and see proposed updates before they're published by checking a public GitHub repository's open PR queue. Community feedback on proposed updates helps the entire community. 15 | 16 | With PR comments and reviews, you can: 17 | 18 | - Add and reply to comments on the PR. 19 | - React to comments with emojis like 👍, ❤️, and 🎉. 20 | 21 | ## Prerequisites 22 | 23 | - [Create a GitHub account](index.md#create-a-github-account), if you don't have one. 24 | 25 | ## Find a PR 26 | 27 | 1. In your browser, navigate to the repository in GitHub that you want to review. If you're not sure which repo to look at, find one that interests you in our [list of Microsoft Learn repos](https://github.com/orgs/MicrosoftDocs/repositories). 28 | 29 | If you're browsing documentation and don't know which repo it belongs to, select the **Edit** pencil icon at the top of the page. This action takes you to the source file on GitHub. The repository name is displayed in the upper-left corner of the page. For example, the following image shows the repo name location for the `azure-dev-docs` repo. 30 | 31 | :::image type="content" source="media/how-to-review-pull-request/find-repo-name.png" alt-text="Screenshot of a GitHub article page showing the repo name in the upper left-hand corner of the page."::: 32 | 33 | 1. Choose the **Pull requests** tab to see the open PRs for that repo. If the repo has a lot of PRs, use the **Filters** bar to filter by label, author, and more. Or use the **Search** bar to look for specific queries. 34 | 35 | :::image type="content" source="media/how-to-review-pull-request/list-of-prs.png" alt-text="Screenshot of a GitHub repo showing the pull requests tab."::: 36 | 37 | 1. Open a PR by selecting the title link. 38 | 39 | ## Review a PR 40 | 41 | 1. In the PR you're reviewing, select the **Files changed** tab. 42 | 43 | :::image type="content" source="media/how-to-review-pull-request/pr-menu.png" alt-text="Screenshot of tabs on the GitHub pull request page. The tab titled Files Changed is highlighted."::: 44 | 45 | 1. Compare the original document to the edited one. The original document will be in red, and the proposed document will be in green. Any added text will be highlighted in the green (new) section, and any deleted text will be highlighted in the red (original) section. 46 | 47 | :::image type="content" source="media/how-to-review-pull-request/compare-docs.png" alt-text="Screenshot of a GitHub Files Changed page. An example of original content highlighted in red and edited content highlighted in green is displayed."::: 48 | 49 | 1. Add comments or suggest changes by selecting the plus (+) icon to the left of the line you'd like to comment on. To select multiple lines, select and drag the plus sign. 50 | 51 | :::image type="content" source="media/how-to-review-pull-request/plus-sign.png" alt-text="Screenshot of a GitHub Files Changed page. The plus sign icon, intended for the user to select to enter in-line comments, is featured."::: 52 | 53 | You can only add comments or suggestions to lines that have been edited in the current PR. To make other changes, [edit that file in your own PR](how-to-write-quick-edits.md). 54 | 55 | 1. A box will open. Enter your comments or questions there. If you'd like, you can use the buttons in the toolbar to format your text, add bulleted and numbered lists, or insert code blocks and images. 56 | 57 | :::image type="content" source="media/how-to-review-pull-request/comment-box.png" alt-text="Screenshot of a GitHub Files Changed page. The comment box element is featured."::: 58 | 59 | 1. You can also suggest a change to the text in that line. 60 | 61 | 1. In the toolbar for the comment, select the **+-** icon (probably the icon furthest to the left). This is the **Insert a suggestion** button. 62 | 63 | :::image type="content" source="media/how-to-review-pull-request/insert-suggestion.png" alt-text="Screenshot of tabs in a comment box on the GitHub Files Changed page. The tab with a + and - icon is highlighted."::: 64 | 65 | 1. The text from the line you selected will be included in a code block (inside two sets of ``` backticks). 66 | 67 | :::image type="content" source="media/how-to-review-pull-request/suggestion-text.png" alt-text="Screenshot of a comment box on the GitHub Files Changed page. An example of how to write the syntax for a suggestion is displayed."::: 68 | 69 | To suggest changes to text that includes a triple-ticked code fence (```), replace the outer/enclosing `suggestion` backticks with tildes (`~~~`). 70 | 71 | 1. Edit the text. Use the buttons in the comment box for simple formatting like bold, italics, and bullets, or use the [Markdown syntax elements](markdown-reference.md) directly. You can also add comments to this box below the code-block section. 72 | 73 | 1. After you've made your comment, select **Start a review**. The PR author will be notified of your changes. If you used the **Insert a suggestion** button in the previous step, the author will be able to commit your suggestion directly to the document. 74 | 75 | If you want to bring someone else into the conversation, you can **@mention** other contributors by their GitHub alias in your comments. Mentioned GitHub users will receive an email containing your comment. You can also use Markdown in your comments, and your comment's Markdown is rendered once you submit the comment. 76 | 77 | 1. In the **Conversations** tab, read through the comments. If you have questions or comments, add them to the conversation. You can also add reactions to comments by selecting the smiley face icon in the bottom-left corner of each comment. 78 | 79 | ## Submit a review 80 | 81 | Once you've added all your comments to the review, submit your review. 82 | 83 | 1. Select the **Review changes** button in the upper-right of the *Files changed* tab to open the review submittal dialog. 84 | 1. Enter a descriptive **Review summary**. 85 | 1. Select the radio button for your desired review type, and then choose **Submit review**. 86 | 87 | ![Submitting a review in GitHub.](media/how-to-review-pull-request/github_comment_07_review-submit.png) 88 | 89 | The PR author will receive notification of the review. 90 | 91 | ## Next steps 92 | 93 | To learn more about commenting and reviews, check out these articles in GitHub's documentation. 94 | 95 | - [Review changes in PRs](https://help.github.com/articles/reviewing-changes-in-pull-requests/) 96 | - [Comment on a PR](https://help.github.com/articles/commenting-on-a-pull-request/) 97 | - [Review proposed changes in a PR](https://help.github.com/articles/reviewing-proposed-changes-in-a-pull-request/) -------------------------------------------------------------------------------- /Contribute/content/how-to-write-overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Overview of editing documentation on Microsoft Learn 3 | description: Learn how to get started editing documentation on Microsoft Learn, and learn how to choose the appropriate method for contribution. 4 | author: carlyrevier 5 | ms.author: cahublou 6 | ms.date: 02/01/2024 7 | ms.topic: contributor-guide 8 | ms.service: learn 9 | ms.custom: external-contributor-guide 10 | --- 11 | 12 | # Overview of editing documentation on Microsoft Learn 13 | 14 | Thank you for your interest in editing documentation on Microsoft Learn! Your contributions help us ensure our documentation is well written, up to date, and accurate. The information on this page will help you decide which method of contribution is best for you. 15 | 16 | ## Prerequisite 17 | 18 | Before you start, make sure you're signed in to your GitHub account. If you don't have a GitHub account, navigate to [https://github.com/join](https://github.com/join) for a fast and free sign-up process. 19 | 20 | ## Minor changes to documentation 21 | 22 | Minor changes are quick and easy. Examples of minor changes include: 23 | 24 | - Fixing typos 25 | - Revising a single article 26 | - Adding a section to an article 27 | - Correcting an error 28 | - Updating broken links 29 | 30 | If you're making minor changes, all you need is a GitHub account! 31 | 32 | To make a minor change, select the **Edit This Document** pencil icon at the top of the article. This action takes you to the source file on GitHub, where you can make your changes. When you're finished, you'll be prompted to create a pull request (PR) to propose your changes. For a full walkthrough of this process, see [Edit documentation in the browser](how-to-write-quick-edits.md). 33 | 34 | ## Major changes to documentation 35 | 36 | Major changes involve more time and effort. Examples of major changes include: 37 | 38 | - Complex changes that will take you several days to complete 39 | - Revisions to multiple articles that you want to submit together 40 | - Creating a new article 41 | - Contributing often 42 | 43 | If you're making major changes, you need to download and install a few tools to make your work easier. Follow these steps to get started: 44 | 45 | 1. [Install Git and Markdown tools.](get-started-setup-tools.md) 46 | 1. [Set up a local Git repository.](get-started-setup-local.md) 47 | 1. [Make changes to the documentation.](how-to-write-major-edits.md) 48 | 1. [Create a PR.](create-pull-request.md) 49 | 50 | ## Process overview 51 | 52 | The process flow below shows the high-level steps involved in getting started for minor and major changes. Notice that some items are one-time steps, while others occur every time you start a new contribution. 53 | 54 | :::image type="complex" source="media/how-to-write-overview/process-diagram.png" alt-text="Process flow map showing the basic workflow for getting started with the contribution process."::: 55 | The image starts with a decision point of Is this your first time contributing? If yes, the next step is to set up your GitHub account. If no, the next step is another decision point of Is your change minor? If yes, the next step is to edit within the browser. If no, the next steps involve installing authoring tools, forking and cloning the repo, making changes, opening a pull request, and reviewing and signing off on your pull request. 56 | :::image-end::: 57 | 58 | ## Changes to training modules 59 | 60 | Contributors can't edit or propose changes to training modules. At this time, only Microsoft Learn documentation stored in public repositories is open for public contributions. 61 | -------------------------------------------------------------------------------- /Contribute/content/how-to-write-quick-edits.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Edit Microsoft Learn documentation in the browser 3 | description: Learn how to edit a Microsoft Learn article in the browser using GitHub's user interface and without having to download or install tools. 4 | author: carlyrevier 5 | ms.author: cahublou 6 | ms.date: 02/01/2024 7 | ms.topic: contributor-guide 8 | ms.service: learn 9 | ms.custom: external-contributor-guide 10 | --- 11 | 12 | # Edit Microsoft Learn documentation in the browser 13 | 14 | > [!TIP] 15 | > A self-paced, [step-by-step learning path](/training/modules/contribute-to-docs-browser/?source=recommendations) is available for this topic. 16 | 17 | Several of Microsoft's documentation sets are open source and hosted on GitHub. While not all documentation sets are completely open source, many have public-facing repositories where you can suggest changes via pull requests (PRs). This open-source approach streamlines and improves communication between product engineers, content teams, and customers. 18 | 19 | Quick edits facilitate the process to report and fix small errors and omissions in documentation. Despite all efforts, small grammar and spelling errors _do_ make their way into our published documents. We appreciate your help in identifying and fixing these issues! 20 | 21 | We use PRs for all changes, even for contributors who have write access. Most repositories protect the default branch, so updates must be submitted as PRs. 22 | 23 | ## Prerequisite 24 | 25 | - [Create a GitHub account](index.md#create-a-github-account), if you don't have one. 26 | 27 | ## Edit a document in the browser 28 | 29 | 1. Navigate to the documentation you want to edit. _Some_ docs pages allow you to edit content directly in the browser. If so, you'll see an **Edit** pencil icon like the one shown below. Choosing the **Edit** pencil icon takes you to the source file on GitHub. 30 | 31 | :::image type="content" source="media/how-to-write-quick-edits/edit-article.png" alt-text="Screenshot of an Azure documentation article showing the **Edit** pencil icon."::: 32 | 33 | If the **Edit** pencil icon isn't present, it means the content isn't open to public contributions. Some pages are generated (for example, from inline documentation in code) and must be edited in the project they belong to. 34 | 35 | 1. Select the **Edit** pencil icon at the top of the GitHub file page. If the **Edit** pencil icon is unavailable (appears dimmed) or doesn't display, you need to log in to your GitHub account. 36 | 37 | :::image type="content" source="media/how-to-write-quick-edits/edit-icon.png" alt-text="Screenshot of the Azure article within GitHub,showing the **Edit** pencil icon."::: 38 | 39 | At the top of the article is the article's metadata. Metadata is applied to articles for reporting, discoverability via search, and driving aspects of the site experience. If you're making minor updates to a published article, you probably won't need to change the metadata. 40 | 41 | 1. If it's your first time working in this repository, you'll be prompted to fork the repo before you propose changes. Select **Fork this repository** to continue. 42 | 43 | 1. Edit the file in the web editor. Choose the **Preview** tab on the toolbar to check the formatting of your changes. 44 | 45 | 1. When you're finished editing, select the **Commit changes** or **Propose changes** button, usually at the top-right of the screen. 46 | 47 | 1. Enter a commit message. The commit message becomes the title of your PR and should be a brief summary of your changes (for example, "Fix spelling and grammar errors"). Optionally, add an **Extended description** to give more details about your changes. Select **Propose changes**: 48 | 49 | :::image type="content" source="media/how-to-write-quick-edits/commit-changes.png" alt-text="Screenshot of the propose changes pop-up."::: 50 | 51 | 1. Now that you've proposed and committed your changes, you need to ask the owners of the repository to "pull" your changes into their repository. This is done using a [pull request](https://docs.github.com/articles/using-pull-requests) (PR). When you select **Propose changes**, you'll see a page like this: 52 | 53 | :::image type="content" source="media/how-to-write-quick-edits/create-pull-request.png" alt-text="Screenshot of the comparing changes screen."::: 54 | 55 | Your PR proposes changes from your fork and branch (represented by the two items on the right side of the arrow) into the documentation repo's main fork and `main` branch (represented by the two items on the left side of the arrow). 56 | 57 | Review your changes, and then select **Create pull request**. 58 | 59 | 1. On the **Open a pull request** page, preview your PR. You can change the title or description fields if needed. When you're ready, select **Create pull request**. This action opens your PR and alerts the article owner that you've proposed a change. 60 | 61 | 1. That's it! Content team members will review your PR and merge it when it's approved. You may get feedback requesting changes. For more details on processing your PR, see [Process a pull request](process-pull-request.md). 62 | 63 | ## Limitations 64 | 65 | - Most localized (i.e., translated) content doesn't offer the ability to edit through GitHub. However, you can provide feedback on translation quality by selecting the Feedback (thumbs) button at the top of the page and then choosing the **Translation quality** reason. You can also leave more specific feedback on localized content by using the [Provide Feedback](https://aka.ms/provide-feedback) form. 66 | - The in-browser editing experience works best for minor and infrequent changes. If you make large contributions or use advanced Git features (such as branch management or advanced merge conflict resolution), we recommend that you [fork the repo and work locally](how-to-write-workflows-major.md). 67 | -------------------------------------------------------------------------------- /Contribute/content/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Contribute to Microsoft Learn 3 | description: Learn how you can contribute to technical documentation and other content experiences on Microsoft Learn. 4 | author: carlyrevier 5 | ms.author: cahublou 6 | ms.date: 08/30/2023 7 | ms.topic: contributor-guide 8 | ms.service: learn 9 | ms.custom: external-contributor-guide 10 | --- 11 | 12 | # Contribute to the Microsoft Learn platform 13 | 14 | Welcome to the Microsoft Learn contributor guide! This documentation introduces you to the ways you can contribute to the Microsoft Learn platform and teaches you how to get started. 15 | 16 | Sharing your expertise with others on Microsoft Learn helps everyone achieve more. Use the information in this guide to publish a new article to Microsoft Learn, update a published article, answer questions on Microsoft Q&A, and more. 17 | 18 | ## Who can contribute? 19 | 20 | Anyone who desires to share their knowledge and make a difference can contribute to Microsoft Learn! If you have expertise to share, you're in the right place. 21 | 22 | This guide is intended for any non-Microsoft employee who wants to contribute their knowledge to the content and experiences on Microsoft Learn. (Are you a Microsoft employee? Use our internal [content contributor guides](/help) instead.) 23 | 24 | ## How do I start? 25 | 26 | > [!TIP] 27 | > A self-paced, [step-by-step learning path](/training/modules/become-learn-contributor) is available for this topic. 28 | 29 | First, set up a few accounts. You'll need a [GitHub account](#create-a-github-account) or a [Microsoft account](#create-a-microsoft-account), depending on how you want to participate. The following table shows your contribution options and the type of account you'll need. 30 | 31 | Once you've set up your accounts, select a contribution option from the table to learn more about how to get started. 32 | 33 | | Contribution option | Account required | 34 | |----------------------------------------------------------------------------------------------|------------------| 35 | | [Edit documentation](how-to-write-overview.md) | GitHub | 36 | | [Review pull requests](how-to-review-pull-request.md) | GitHub | 37 | | [Provide feedback on content](provide-feedback.md) | None for standard experience; GitHub for open-source experience | 38 | | [Create GitHub issues for open-source product documentation](how-to-create-github-issues.md) | GitHub | 39 | | [Answer questions on Microsoft Q&A](qna-overview.md) | Microsoft | 40 | | [Create a Collection](collections.md) | Microsoft | 41 | | [Participate in the Microsoft Learn Tech Community](https://techcommunity.microsoft.com/t5/microsoft-learn/ct-p/MicrosoftLearn) | Microsoft | 42 | 43 | ### Create a GitHub account 44 | 45 | 1. Navigate to [https://github.com/join](https://github.com/join) for a fast and free sign-up process. 46 | 1. In your GitHub profile, identify your affiliations, like professional organizations you belong to or credentials/certifications you've earned. Contributions to Microsoft Learn count toward [MVP award](https://mvp.microsoft.com/) consideration. Identification helps us build a complete profile of all your activities. 47 | 48 | >[!NOTE] 49 | > Microsoft employees participating in Open Source projects always identify themselves as such in their GitHub profiles. Community contributors should ensure that their profile does not incorrectly imply an employment relationship. 50 | 51 | ### Create a Microsoft account 52 | 53 | 1. Navigate to [learn.microsoft.com](/). 54 | 1. Select **Sign in** in the upper-right corner. 55 | 1. Follow the prompts to create a Microsoft account and profile. 56 | 1. Once created, visit [Managing your Microsoft Learn profile settings](/training/support/learn-profile-manage) to learn how to update your Microsoft Learn profile. 57 | 58 | ## What's in it for me? 59 | 60 | Explore Microsoft Learn and discover how it's a win-win for everyone, especially you! Every time you edit our documentation, we celebrate your contribution by featuring your name at the top of the article. 61 | 62 | Each commit you make to our GitHub repositories is a testament to your dedication, prominently displayed in your GitHub commit history. This not only demonstrates your passion for specific technologies but also fortifies your portfolio. 63 | 64 | And the cherry on top? Some products even reward you with digital treats like badges. 65 | 66 | So don't hold back! Dive in, contribute, and enjoy the perks! 67 | -------------------------------------------------------------------------------- /Contribute/content/media/alerts-rendering.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/alerts-rendering.png -------------------------------------------------------------------------------- /Contribute/content/media/code-in-docs/highlighted-code.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/code-in-docs/highlighted-code.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/add-section.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/add-section.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/add-to-collection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/add-to-collection.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/copy-collection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/copy-collection.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/create-article.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/create-article.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/create-code-samples.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/create-code-samples.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/create-collection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/create-collection.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/create-from-item.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/create-from-item.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/create-module.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/create-module.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/delete-collection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/delete-collection.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/profile.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/profile.png -------------------------------------------------------------------------------- /Contribute/content/media/collections/share-collection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/collections/share-collection.png -------------------------------------------------------------------------------- /Contribute/content/media/create-pull-request/comparing-changes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/create-pull-request/comparing-changes.png -------------------------------------------------------------------------------- /Contribute/content/media/create-pull-request/create-pr-compare.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/create-pull-request/create-pr-compare.png -------------------------------------------------------------------------------- /Contribute/content/media/documents/markdown-cheatsheet.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/documents/markdown-cheatsheet.pdf -------------------------------------------------------------------------------- /Contribute/content/media/get-started-setup-local/code-drop-down.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/get-started-setup-local/code-drop-down.png -------------------------------------------------------------------------------- /Contribute/content/media/get-started-setup-local/create-a-new-fork.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/get-started-setup-local/create-a-new-fork.png -------------------------------------------------------------------------------- /Contribute/content/media/get-started-setup-local/fork.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/get-started-setup-local/fork.png -------------------------------------------------------------------------------- /Contribute/content/media/get-started-setup-local/forked-repo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/get-started-setup-local/forked-repo.png -------------------------------------------------------------------------------- /Contribute/content/media/get-started-setup-local/git-and-github-initial-setup.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/get-started-setup-local/git-and-github-initial-setup.png -------------------------------------------------------------------------------- /Contribute/content/media/get-started-setup-local/gitbash-start.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/get-started-setup-local/gitbash-start.png -------------------------------------------------------------------------------- /Contribute/content/media/get-started-setup-local/github-2fa.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/get-started-setup-local/github-2fa.png -------------------------------------------------------------------------------- /Contribute/content/media/get-started-setup-local/github-login.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/get-started-setup-local/github-login.png -------------------------------------------------------------------------------- /Contribute/content/media/get-started-setup-local/pencil-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/get-started-setup-local/pencil-icon.png -------------------------------------------------------------------------------- /Contribute/content/media/get-started-setup-local/repo-name.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/get-started-setup-local/repo-name.png -------------------------------------------------------------------------------- /Contribute/content/media/hacktoberfest/github-topic.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/hacktoberfest/github-topic.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-create-github-issues/comment-issue.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-create-github-issues/comment-issue.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-create-github-issues/feedback-links.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-create-github-issues/feedback-links.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-create-github-issues/github-issue.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-create-github-issues/github-issue.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-create-github-issues/pr-open-issue.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-create-github-issues/pr-open-issue.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-review-pull-request/comment-box.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-review-pull-request/comment-box.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-review-pull-request/compare-docs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-review-pull-request/compare-docs.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-review-pull-request/find-repo-name.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-review-pull-request/find-repo-name.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-review-pull-request/github_comment_07_review-submit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-review-pull-request/github_comment_07_review-submit.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-review-pull-request/insert-suggestion.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-review-pull-request/insert-suggestion.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-review-pull-request/list-of-PRs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-review-pull-request/list-of-PRs.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-review-pull-request/plus-sign.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-review-pull-request/plus-sign.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-review-pull-request/pr-menu.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-review-pull-request/pr-menu.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-review-pull-request/suggestion-text.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-review-pull-request/suggestion-text.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-links/bookmark-link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-links/bookmark-link.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-links/ms-assetid.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-links/ms-assetid.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-major-edits/commit-changes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-major-edits/commit-changes.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-major-edits/select-source-control.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-major-edits/select-source-control.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-major-edits/sync-changes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-major-edits/sync-changes.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-major-edits/vscode-branch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-major-edits/vscode-branch.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-overview/process-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-overview/process-diagram.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-quick-edits/commit-changes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-quick-edits/commit-changes.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-quick-edits/create-pull-request.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-quick-edits/create-pull-request.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-quick-edits/edit-article.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-quick-edits/edit-article.png -------------------------------------------------------------------------------- /Contribute/content/media/how-to-write-quick-edits/edit-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/how-to-write-quick-edits/edit-icon.png -------------------------------------------------------------------------------- /Contribute/content/media/markdown-reference/document.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/markdown-reference/document.png -------------------------------------------------------------------------------- /Contribute/content/media/markdown-reference/long-description.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/markdown-reference/long-description.png -------------------------------------------------------------------------------- /Contribute/content/media/provide-feedback/feedback-box.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/provide-feedback/feedback-box.png -------------------------------------------------------------------------------- /Contribute/content/media/provide-feedback/feedback-link-training.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/provide-feedback/feedback-link-training.png -------------------------------------------------------------------------------- /Contribute/content/media/provide-feedback/feedback-link.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/provide-feedback/feedback-link.png -------------------------------------------------------------------------------- /Contribute/content/media/provide-feedback/history.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/provide-feedback/history.png -------------------------------------------------------------------------------- /Contribute/content/media/provide-feedback/open-source.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/content/media/provide-feedback/open-source.png -------------------------------------------------------------------------------- /Contribute/content/metadata.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Metadata for Microsoft Learn documentation 3 | description: Learn about the required and optional metadata for Microsoft Learn documentation. 4 | author: sarah-barrett 5 | ms.author: sabarret 6 | ms.date: 05/01/2025 7 | ms.topic: contributor-guide 8 | ms.service: learn 9 | ms.custom: external-contributor-guide 10 | --- 11 | 12 | # Metadata for Microsoft Learn documentation 13 | 14 | Metadata can be applied in the article (in the YAML front matter) or globally in the *docfx.json* file for the repo. If you're making an edit to an existing article, you probably won't have to change any metadata. However, if you're adding a new article, there are certain required metadata attributes that you'll need to include in the YAML front matter of the file. 15 | 16 | Here's an example of metadata applied in the YAML front matter of a Markdown article: 17 | 18 | ```md 19 | --- 20 | title: # the article title to show on the browser tab 21 | description: # 115 - 145 character description to show in search results 22 | author: {github-id} # the author's GitHub ID - will be auto-populated if set in settings.json 23 | ms.author: {ms-alias} # the author's Microsoft alias (if applicable) - will be auto-populated if set in settings.json 24 | ms.date: {@date} # the date - will be auto-populated when template is first applied 25 | ms.topic: getting-started # the type of article 26 | --- 27 | # Heading 1 28 | ``` 29 | 30 | ## Required metadata 31 | 32 | The following table shows the required metadata attributes. If you omit any of these, you'll likely get a validation error during build. 33 | 34 | | Field | Value | Why? | 35 | | ----- | ----- | ---- | 36 | | author | The author's GitHub account ID. | Identifies the author by GitHub ID in case there are questions about or problems with the content. In some cases, GitHub automation might notify the author of activity involving the file. | 37 | | description | A summary of the content. 75-300 characters. | Used in site search. Sometimes used on a search engine results page for improved SEO. | 38 | | ms.author |The author's Microsoft alias, *without* "@microsoft.com". If you aren't a Microsoft employee, find a suitable Microsoft employee to use in this field. | Identifies the article's owner. The owner is responsible for decisions about the content of the article, and for the article's reporting and BI. | 39 | | ms.date | A date in the format MM/DD/YYYY. | Displayed on the published page to indicate the last time the article was substantially edited or guaranteed fresh. The date is entered without time and is interpreted as 0:00 and in the UTC time zone. The date displayed to users is converted to their time zone. | 40 | | title | The page title. | This is the page title that's displayed on the browser tab. It's the most important metadata for SEO. | 41 | 42 | Attributes are case-sensitive. Enter them exactly as listed, and use a colon and a space between the attributes and the value. If an attribute value includes a colon (:), a hash (#), or any other special character, you must enclose it either single (') or double (") quotes. For example: 43 | 44 | ```md 45 | --- 46 | title: 'Quickstart: How to use hashtags (#) to make a point on the internet' 47 | --- 48 | # Heading 1 49 | ``` 50 | -------------------------------------------------------------------------------- /Contribute/content/powershell-overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: How to contribute to PowerShell documentation 3 | description: This article is an overview of how to get started as a contributor to the PowerShell documentation. 4 | ms.date: 07/10/2020 5 | ms.topic: contributor-guide 6 | ms.service: learn 7 | ms.custom: external-contributor-guide 8 | author: sdwheeler 9 | ms.author: sewhee 10 | --- 11 | # How to contribute to PowerShell documentation 12 | 13 | The contributor guide is a collection of articles that explain the tools and processes we use to create documentation at Microsoft. Some of these guides cover information that is common to any documentation set published to Microsoft technical documentation. Some of the guides are specific to how we write documentation for PowerShell. 14 | 15 | The common articles are available in this centralized contributor guide. The 16 | [PowerShell contributor guide](/powershell/scripting/community/contributing/overview) is available in the community section of the PowerShell documentation. 17 | -------------------------------------------------------------------------------- /Contribute/content/process-pull-request.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Process a pull request 3 | description: This article explains what happens after you open a pull request in GitHub for your contribution to Microsoft Learn. 4 | author: carlyrevier 5 | ms.author: cahublou 6 | ms.topic: contributor-guide 7 | ms.service: learn 8 | ms.custom: external-contributor-guide 9 | ms.date: 01/25/2024 10 | --- 11 | 12 | # Process a pull request 13 | 14 | After you've opened a pull request (PR), the PR undergoes a set of checks and reviews to ensure your proposed changes can be merged. For more background on PRs, see [Git and GitHub fundamentals](git-github-fundamentals.md#pull-requests). 15 | 16 | ## Validation 17 | 18 | Before your PR can be merged into its destination branch, it might be required to pass through one or more PR-validation processes. After you select **Create pull request**, GitHub runs the validations configured for your repository. When the validation process finishes, the results appear in the PR. 19 | 20 | Validation processes vary depending on the scope of proposed changes and the rules of the destination repository. After you submit your PR, you can expect one or more of the following to happen: 21 | 22 | - **Mergeability**: A baseline GitHub mergeability test occurs first to verify whether the proposed changes in your branch conflict with the destination branch. If the PR indicates this test failed, you must reconcile the content that is causing the merge conflict before processing can continue. 23 | - **Contribution License Agreement (CLA)**: As a non-Microsoft contributor, if you're contributing to a public repository, you might be asked to complete a short CLA the first time you submit a PR to that repository. After the CLA step is cleared, your PR is processed. 24 | - **Labeling**: Labels are automatically applied to your PR to indicate the state of your PR as it passes through the validation workflow. For instance, new PRs might automatically receive the "do-not-merge" label, indicating that the PR hasn't yet completed the validation, review, and sign-off steps. 25 | - **Validation and build**: Automated checks verify whether your changes pass validation tests. The validation tests might yield warnings or errors, requiring you to edit one or more files in your PR before it can be merged. The validation test results are added as a comment in your PR for your review, and they might be sent to you in e-mail. 26 | - **Staging**: Upon successful validation and build, the articles you changed are automatically deployed to a staging environment for review. Preview URLs appear in a PR comment. 27 | - **Auto-merge**: The PR might be automatically merged if it passes validation testing and certain criteria. In this case, you don't need to do anything else. 28 | 29 | ## Review and address feedback 30 | 31 | After all PR processing is complete, you should review the results (for example, PR comments, build results). Determine if you need to make more changes before you sign off for merging. You may need to change your content for any of the following reasons: 32 | 33 | - PR comments from reviewers. If a PR reviewer has reviewed your PR, they can provide feedback via comments if there are outstanding issues or questions to be resolved before merge. 34 | - Feedback from peer reviewers. 35 | - Formatting fixes due to rendering issues. 36 | - Validation errors or warnings. 37 | - Merge conflicts. 38 | 39 | If you need to make changes, you can edit your content directly in the PR, or you can return to VS Code to make your changes. When you're finished, commit your changes to your working branch. The PR is automatically updated with your changes. 40 | 41 | Each time you add a commit to the same working branch, the commit is added automatically to the PR. With each commit, the publishing system reruns the validation and review processes automatically. 42 | 43 | ## Sign-off and comment automation 44 | 45 | When you've addressed all feedback and validation errors, and you're ready for your changes to be merged, it's time to sign off on your PR by creating a new comment that reads `#sign-off`. You must enter the `#sign-off` comment to merge your changes. Even if all reviews and validation checks pass, you're responsible for using this comment to tell the PR reviewers and repo admins that your changes are ready for merging. 46 | 47 | When the reviewers determine that your PR is issue-free and signed off, your changes are merged into the default branch and the PR is closed. 48 | 49 | Comment automation enables users who don't have write permissions in a repo to complete a write-level action by assigning the appropriate label to a PR. If you're working in a repo where comment automation has been implemented, use the **hashtag comments** listed in the following table to assign labels, change labels, or close a PR. Microsoft authors will also be notified via e-mail for review and sign-off whenever changes are proposed to their articles. 50 | 51 | | Hashtag comment | What it does | 52 | | --- | --- | --- | 53 | | `#sign-off` | Automatically assigns the **ready-to-merge** label to let the reviewers in the repo know the PR is ready for review/merge.

If you're not the listed author and try to sign off on a public-repo PR using the #sign-off comment, the PR is updated to indicate that only the author can assign the label. | 54 | | `#hold-off` | Removes the **ready-to-merge** label in case you change your mind or make a mistake. In the private repo, this assigns the **do-not-merge** label. | 55 | | `#please-close` | Closes the PR if you decide not to have the changes merged. | 56 | | `#please-open` | Reopens a closed PR or issue. | 57 | 58 | ## Publishing 59 | 60 | Your PR has to be merged by a PR reviewer before the changes can be included in the next scheduled publishing run. Normally, PRs are reviewed and merged in the order of submission. 61 | 62 | After your contributions are approved and merged, the publishing process picks them up. Depending on the team that manages the repository you’re contributing to, publishing times can vary, but they typically occur at least once every weekday. It can take up to 45 minutes for articles to appear online after publishing. 63 | 64 | Once your changes are published, they go live on Microsoft Learn for others to start learning from! 65 | 66 | ## Next steps 67 | 68 | That's it! You've made a contribution to Microsoft Learn content! 69 | -------------------------------------------------------------------------------- /Contribute/content/provide-feedback.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Provide feedback for Microsoft Learn content 3 | description: Learn how to provide feedback to Microsoft Learn content teams using the new feedback experience for documentation and training content. 4 | author: carlyrevier 5 | ms.author: cahublou 6 | ms.topic: contributor-guide 7 | ms.service: learn 8 | ms.custom: external-contributor-guide 9 | ms.date: 02/22/2024 10 | --- 11 | 12 | # Provide feedback for Microsoft Learn content 13 | 14 | This article explains how to provide feedback for Microsoft Learn content using the new feedback experience. This unified feedback experience is now standard across all documentation or training content on Microsoft Learn. The new system: 15 | 16 | - Unifies our systems to efficiently incorporate your feedback, including better routing for customer feedback to our support, product, and content teams. 17 | - Supports global accessibility for non-English learners. 18 | - Allows for anonymous feedback to protect learner privacy. 19 | - Supports the variety of people who use Microsoft Learn, not all of whom use GitHub regularly. 20 | 21 | All content on Microsoft Learn uses the new standard experience. Depending on the repository, you may see an open-source experience in addition to the standard feedback experience. 22 | 23 | While GitHub issues are no longer supported in repositories using only the standard experience, you can still contribute to Microsoft Learn documentation by [creating a pull request](how-to-write-quick-edits.md) if you spot an error or wish to add something for any repository that already had this capability enabled. Also, you can still view an article's change history and contributors by selecting the **Edit** pencil at the top of the page and then selecting **History**: 24 | 25 | :::image type="content" source="media/provide-feedback/history.png" alt-text="Screenshot of the history button in GitHub for the web."::: 26 | 27 | ## Prerequisites 28 | 29 | - None, if using the [standard experience](#use-the-standard-experience). 30 | - A GitHub account, if using the [open-source experience](#use-the-open-source-experience). 31 | 32 | ## Use the standard experience 33 | 34 | The new standard experience allows you to provide feedback using a thumbs up/thumbs down control. You don’t need to log in or create an account to use this experience. 35 | 36 | To leave feedback using the standard experience: 37 | 38 | 1. Navigate to the article you’d like to give feedback on. 39 | 1. Find the **Feedback** link and select it. 40 | 1. In documentation that has only the standard experience enabled, the link is at the top of the page and in a larger box at the bottom of the page. 41 | 42 | ![Screenshot of the feedback link at the top of a documentation page.](media/provide-feedback/feedback-link.png) 43 | 44 | 1. In training modules, the link is at the top of the module’s landing page and at the bottom of each unit within the module. 45 | 46 | ![Screenshot of the feedback link at the top of a training module.](media/provide-feedback/feedback-link-training.png) 47 | 48 | 1. Choose the thumbs up option if you found the page helpful; choose the thumbs down option if it wasn’t. 49 | 1. Choose one or multiple reasons for your feedback. Optionally, we highly encourage you to use the comment box (which supports up to 999 characters of text) to provide specific feedback on the content. 50 | 51 | ![Screenshot of the feedback control.](media/provide-feedback/feedback-box.png) 52 | 53 | Readers of localized content will see an additional option to provide feedback on the translation quality. 54 | 55 | The feedback control allows you to provide feedback on Microsoft Learn content. Your feedback will be evaluated by Microsoft content writers, not product teams. 56 | 57 | Some content teams may also configure these other links to appear at the bottom of the feedback control: 58 | 59 | - **Provide product feedback**: This link allows you to provide feedback for the product itself rather than the content. Selecting this link will take you to a platform where you can provide feedback on the product, which is reviewed by the respective product teams. 60 | - **Get help**: Depending on how this link is configured, it takes you to either the product's community site or the Q&A platform. If you have specific questions and require community assistance, you can use these platforms to get help. 61 | 62 | 1. Select **Submit**. 63 | 64 | > [!NOTE] 65 | > The feedback you provide is anonymous, and Microsoft doesn’t collect personal data from your submission. In the new experience, feedback isn’t publicly visible to ensure customer privacy. You won't receive a response after you submit your feedback. 66 | 67 | ## Use the open-source experience 68 | 69 | The open-source feedback experience allows open-source communities to use GitHub issues for documentation related to open-source products. When enabled, this hybrid experience includes the standard feedback experience at the top of the page and an option to open a GitHub issue at the bottom of the page: 70 | 71 | :::image type="content" source="media/provide-feedback/open-source.png" alt-text="Screenshot of the open-source experience at the bottom of a documentation page."::: 72 | 73 | To open a GitHub issue, you must have a GitHub account. For more information, see [Create GitHub issues](how-to-create-github-issues.md). 74 | 75 | ## Related content 76 | 77 | - [Edit documentation in the browser](how-to-write-quick-edits.md) -------------------------------------------------------------------------------- /Contribute/content/qna-overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Answer questions on Microsoft Q&A 3 | description: Provides contributor-relevant links to the Microsoft Q&A support repo. 4 | author: carlyrevier 5 | ms.author: cahublou 6 | ms.date: 09/11/2023 7 | ms.topic: contributor-guide 8 | ms.service: learn 9 | ms.custom: external-contributor-guide 10 | --- 11 | 12 | # Answer questions on Microsoft Q&A 13 | 14 | This article provides links to Microsoft Q&A guidance that applies to contributors who answer questions on the [Microsoft Q&A platform](/answers). Select a topic below, or browse the full [Microsoft Q&A support guide](/answers/support). 15 | 16 | | Article | Description | 17 | |----------|-----------| 18 | |[Answer questions](/answers/support/answer-question) | Learn how to find and answer questions on the Microsoft Q&A platform. | 19 | |[Write a quality answer](/answers/support/quality-answer) | Learn what makes a good answer and how to write one.| 20 | |[Add attachments](/answers/support/attachments) | Learn how to add attachments to complement your answers or comments.| 21 | |[Add comments](/answers/support/post-comment)|Learn how to add brief messages to clarify a question, answer or comment or add more information.| 22 | |[Accept an answer](/answers/support/accept-answer) | Learn how to accept an answer to your question as the question author.| 23 | |[Answer your own questions](/answers/support/self-answering) | Learn how and when to answer your own questions.| 24 | |[Search for questions](/answers/support/search) | Learn how to search for questions with Microsoft Q&A if you're looking for specific topics to answer.| 25 | |[Filter and sort content](/answers/support/filter-sort) | Learn how to filter and sort content on Microsoft Q&A, including filtering for unanswered questions.| 26 | |[Report content for moderation](/answers/support/report) | Learn how to report a question, answer, or comment for moderation if you feel it doesn't follow our Code of Conduct.| 27 | -------------------------------------------------------------------------------- /Contribute/content/seo-reference.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: SEO quick reference guide 3 | description: Explore this SEO quick reference guide with writing tips to improve on-page search engine optimization. Make your online content more discoverable by search engines and LLMs. 4 | author: ps0394 5 | ms.author: paulsanders 6 | ms.date: 12/04/2023 7 | ms.topic: contributor-guide 8 | ms.service: learn 9 | ms.custom: external-contributor-guide 10 | --- 11 | 12 | # SEO quick reference guide 13 | 14 | Use these search engine optimization (SEO) tips as a quick reference to the basics of on-page SEO for contributors to Microsoft Learn. This guide can be an effective tool in optimizing your content once you've done your keyword research and aligned your content with user intent. Adhering to these SEO best practices can improve your overall content quality and discoverability by users, search engines, and large language models (LLMs). 15 | 16 | ## Search results: main elements 17 | 18 | - [**Meta title:**](#meta-titles) The meta title is entered in the YAML header in a Markdown document (or between the head tags in HTML). It's displayed on the search engine results page (SERP) and browser tab. It's the title that describes the entire page. It has the greatest impact on search rank and click-through rate (CTR). The meta title isn't the same as the main heading (H1) on the page. 19 | - [**URL:**](#optimized-url) Once chosen, the URL shouldn't be changed because it affects tracking. Changing the URL could send conflicting signals to search engines. The URL should be concise and specific to aid search engines and improve user experience. 20 | - [**Meta description:**](#meta-description) The meta description is also entered in the YAML header in a Markdown document (or between the head tags in HTML). It's displayed in the SERPs below the URL and meta title. This short block of text gives users a preview of what your pages is about. It has a positive impact on CTR and should be a summary that entices users to click. 21 | 22 | ## View meta title and description in Visual Studio Code 23 | 24 | The [Learn Authoring Pack](/contribute/content/get-started-setup-tools?pivots=windows-os-pivot-selection#install-learn-authoring-pack) for Visual Studio Code includes a Search Results Preview to help verify that your title and description are helpful to users when returned in search results. Access the Command Palette with **ALT + M** and select **Search Results Preview**. 25 | 26 | ## SEO best practices 27 | 28 | - **Keyword placement**: Use the primary keyword near the beginning of the meta title, meta description, H1, introduction, H2s, and image text whenever possible. 29 | - **Use terms that address intent.** 30 | - **Be specific.** Use exact terms for products, features, errors, etc., that are likely to match queries put into search engines. Don't use acronyms, unless widely known, such as DNS. 31 | 32 | ## Meta titles 33 | 34 | The meta title should be clear and concise, and it should include the primary keyword. For example, for a tutorial on Python programming, a suitable meta title could be "Python Mastery: A Comprehensive Guide for Beginners." This title not only includes the primary keyword "Python" but also provides a glimpse into the content focus. It should also: 35 | 36 | - **Be the right length.** For optimal SEO, write the title so that the entire title is 30-65 characters long. The entire title is: Meta title + meta titleSuffix + suffix "| Microsoft Learn." (Some teams use titleSuffix metadata to add the product name. If your team doesn't use titleSuffix then add the product brand name into the meta title.) 37 | - **Be written in title case.** This means to capitalize every word except for small words such as "a, an, the, of," etc. 38 | - **Show enough information** for users to determine relevance. 39 | - **Describe a specific scenario or benefit.** 40 | 41 | ## Optimized URL 42 | 43 | The page URL displays in the search result and contributes to rank and relevance. 44 | 45 | - Follow the URL convention for your site. 46 | - Should be 75 characters max using lowercase letters, numbers, and hyphens. 47 | - Use key terms from the meta title and H1. 48 | 49 | ## Meta description 50 | 51 | The meta description allows search engines and users to understand the page content. 52 | 53 | - Should be between 120 and 165 characters, including spaces. 54 | - Describes the specific scenario and/or benefit of the article. 55 | - Entices users to click through to the page. 56 | 57 | ## Main heading (H1) 58 | 59 | The H1 heading is the main heading at the top of an article. The H1 is the second-most important text string for search rank and relevance. There's only one H1 per article. H1 isn't the same as the [meta title](#meta-titles). 60 | 61 | It’s ok to copy the meta title, but, when possible, make it more unique and specific. At a minimum, repeat key terms. 62 | 63 | ## Sub-headings (H2-H3) 64 | 65 | H2s divide the primary sections on a page, making it easy for users and search engines to understand the content on the page. Search engines often display H2s as additional links below the metadata description on the SERP. Make them specific and descriptive of a section’s content. Avoid writing one- or two-word headings. Use a heading hierarchy (H2-H3) without skipping a level. 66 | 67 | ## Image filenames and alt text 68 | 69 | Image filenames and alt text can get a page-one result in the image carousel, even if your article isn’t on page one of search otherwise. Although image alt text is primarily an accessibility feature, you can include your primary keyword in the description if it makes sense. Here are some best practices for images and alt text when used in articles: 70 | 71 | - **Alt text:** Describe the image in simple language. Use at least 40 characters but no more than 150 characters. Alt text is important because it helps search engines understand the image and increases accessibility for users. Don't include language like “image of.” 72 | - **Image filename:** Use letters, numbers, and hyphens only to a maximum of 80 characters, including spaces. Describe the image and include your primary keyword if it makes sense. 73 | -------------------------------------------------------------------------------- /Contribute/content/style-quick-start.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Microsoft Learn style guide - Quick start 3 | description: This article is a concise guide for style considerations, containing just the essential topics for getting started with Microsoft Learn. 4 | ms.topic: contributor-guide 5 | ms.service: learn 6 | ms.custom: external-contributor-guide 7 | ms.date: 07/25/2017 8 | --- 9 | # Microsoft Learn style and voice quick start 10 | 11 | This quick start is a brief guide to writing technical content for publication on Microsoft Learn. These guidelines apply whether you are creating new documentation or updating existing documentation. 12 | 13 | Best practices: 14 | 15 | - Check the spelling and grammar in your articles, even if you have to copy and paste into Microsoft Word to check. 16 | - Use a casual and friendly voice—like you're talking to another person one-on-one. 17 | - Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share. 18 | 19 | ## Use the Microsoft voice principles 20 | 21 | We aspire to follow these principles when we write technical content for [Microsoft Learn](/). We might not always get there, but we need to keep trying! 22 | 23 | - **Focus on the intent**: Customers have a specific purpose in mind when they consult our documentation. Before you begin writing, clearly determine who the customer is and what task he or she is trying to do. Then, write your article to help that specific customer do that specific task. 24 | - **Use everyday words**: Try to use natural language, the words your customers use. Be less formal but not less technical. Provide examples that explain new concepts. 25 | - **Write concisely**: Don't waste words. Be affirmative and don't use extra words or lots of qualifiers. Keep sentences short and concise. Keep your article focused. If a task has a qualifier, put it at the beginning of the sentence or paragraph. Also, keep the number of notes to a minimum. Use a screenshot when it can save words. 26 | - **Make your article easy to scan**: Put the most important things first. Use sections to chunk long procedures into more manageable groups of steps. (Procedures with more than 12 steps are probably too long.) Use a screenshot when it adds clarity. 27 | - **Show empathy**: Use a supportive tone in the article, and keep disclaimers to a minimum. Honestly call out areas that will be frustrating to customers. Make sure the article focuses on what matters to customers; don't just give a technical lecture. 28 | 29 | ## Consider localization and machine translation 30 | 31 | Our technical articles are translated into several languages, and some are modified for particular markets or geographies. People might also use machine translation on the web to read the technical articles. So, keep the following guidelines in mind when you're writing: 32 | 33 | - **Make sure the article contains no grammar, spelling, or punctuation errors**: This is something we should do in general. Some Markdown editors (such as MarkdownPad 2.0) have a basic spell checker, but it's a good practice to paste the rendered HTML content from the article into Word, which has a more robust spell and grammar checker. 34 | - **Make your sentences as short as possible**: Compound sentences or chains of clauses make translation difficult. Split up sentences if you can do it without being too redundant or sounding weird. We don't want articles written in unnatural language either. 35 | - **Use simple and consistent sentence construction**: Consistency is better for translation. Avoid parentheticals and asides, and have the subject as near the beginning of the sentence as possible. Check out a few published articles. If an article has a friendly, easy-to-read style, use it as a model. 36 | - **Use consistent wording and capitalization**: Again, consistency is key. Do not capitalize a word if it isn't at the start of a sentence or it isn't a proper noun. 37 | - **Include the "small words"**: Words that we consider small and unimportant in English because they are understood for context (such as "a," "the," "that," and "is") are crucial for machine translation. Be sure to include them. 38 | 39 | ## Other style and voice issues to watch for 40 | 41 | - Don't break up steps with commentary or asides. 42 | - For steps that include code snippets, put additional information about the step into the code as comments. This reduces the amount of text that people have to read through. The key information gets copied into the code project to remind people of what the code is doing when they refer to it later. 43 | - Use sentence case for all titles and headings. 44 | - Use "sign in" and not "log in." 45 | - For more guidelines, see the [Microsoft Writing Style Guide](/style-guide/welcome). 46 | 47 | ## Localized documentation 48 | 49 | - If you are contributing to localized documentation, refer to the [globalization references](https://learn.microsoft.com/globalization/reference/). 50 | - For localization guidelines, information on language style and usage in technical publications, and information on market-specific data formats, download the [style guide](https://learn.microsoft.com/globalization/reference/microsoft-style-guides) in your language. 51 | - Visit [Microsoft Terminology](https://learn.microsoft.com/globalization/reference/microsoft-terminology) to search for product-specific approved terminology or to download the Microsoft Terminology Collection in your language. 52 | - To learn more about localization, see "Global communications" in the [Microsoft Writing Style Guide](/style-guide/global-communications). 53 | 54 | [!INCLUDE [note-docsitelocfeedback](../includes/note-docsitelocfeedback.md)] 55 | -------------------------------------------------------------------------------- /Contribute/content/text-formatting-guidelines.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Text formatting guidelines 3 | description: Learn when to use bold, italics, code, and other text styles in articles published on Microsoft Learn. 4 | author: tdykstra 5 | ms.author: tdykstra 6 | ms.date: 11/09/2021 7 | ms.service: learn 8 | ms.topic: contributor-guide 9 | ms.custom: external-contributor-guide 10 | --- 11 | 12 | # Text formatting guidelines 13 | 14 | Consistent and appropriate use of bold, italic, and code style for text elements improves readability and helps avoid misunderstandings. If a text formatting element isn't covered by this guidance, refer to the [Microsoft Writing Style Guide](/style-guide/welcome/). The following articles provide detailed guidance on text formatting: 15 | 16 | - [Formatting common text elements](/style-guide/text-formatting/formatting-common-text-elements) 17 | 18 | - [Formatting text in instructions](/style-guide/procedures-instructions/formatting-text-in-instructions) 19 | 20 | - [Formatting common developer elements](/style-guide/developer-content/formatting-developer-text-elements) 21 | 22 | ## UI elements 23 | 24 | UI elements, like menu items, dialog names, and names of text boxes, should be in bold text. 25 | 26 | - **This**: In **Solution Explorer**, right-click the project node, and then select **Add** > **New Item**. 27 | 28 | - **Not this**: In Solution Explorer, right-click the project node, and then select Add > New Item. 29 | 30 | ## Git repo and branch names 31 | 32 | Use bold text for Git repo or branch names when selected or entered in instructions. 33 | 34 | - **This**: From the branch menu, select **main**. 35 | 36 | - **Not this**: From the branch menu, select "main". 37 | 38 | ## New term introductions 39 | 40 | Use italic text to introduce a new term along with a definition or explanation. Italicize the new term the first time you use it, and then use regular text for the definition or explanation. 41 | 42 | - **This**: In App Service, an app runs in an *App Service plan*. An App Service plan defines a set of compute resources for a web app to run on. 43 | 44 | - **Not this**: In App Service, an app runs in an "App Service plan." An App Service plan defines a set of compute resources for a web app to run on. 45 | 46 | ## Code style 47 | 48 | Use code style for: 49 | 50 | * Code elements, such as method names, property names, and language keywords. 51 | * SQL commands 52 | * NuGet package names 53 | * Command-line commands\* 54 | * Database table and column names 55 | * Resource names that should not be localized (such as virtual machine names) 56 | * URLs that you don't want to be clickable 57 | 58 | **Why?** Some style guides specify bold for many of these text elements. However, most articles are localized, and code style tells the translator to leave that part of the text untranslated. 59 | 60 | Code style can be *inline* (surrounded by \`) or *fenced* code blocks (surrounded by \`\`\`) that span multiple lines. Put longer code snippets and paths in fenced code blocks. 61 | 62 | \* In command-line commands, use forward slashes in file paths if they're supported on all platforms. Use backslashes to illustrate commands that run on Windows, when only backslashes are supported. For example, forward slashes work on the .NET CLI on all platforms, so you would use `dotnet build foldername/filename.csproj` rather than `dotnet build foldername\filename.csproj`. 63 | 64 | ### Examples using inline styles 65 | 66 | * **This**: By default, the Entity Framework interprets a property that's named `Id` or `ClassnameID` as the primary key. 67 | * **Not this**: By default, the Entity Framework interprets a property that's named *Id* or *ClassnameID* as the primary key. 68 | * **This**: The `Microsoft.EntityFrameworkCore` package provides runtime support for EF Core. 69 | * **Not this**: The *Microsoft.EntityFrameworkCore* package provides runtime support for EF Core. 70 | 71 | ### Examples of fenced code blocks 72 | 73 | * **This**: No commands are sent to the database by statements that just change an `IQueryable`, such as the following code: 74 | 75 | ```markdown 76 | ```csharp 77 | var students = context.Students.Where(s => s.LastName == "Davolio") 78 | ``` 79 | ``` 80 | 81 | * **Not this**: No commands are sent to the database by statements that just change an **IQueryable**, such as **var students = context.Students.Where(s => s.LastName == "Davolio")**. 82 | 83 | * **This**: For example, to run the `Get-ServiceLog.ps1` script in the `C:\Scripts` directory, type: 84 | 85 | ```markdown 86 | ```powershell 87 | C:\Scripts\Get-ServiceLog.ps1 88 | ``` 89 | ``` 90 | 91 | * **Not this**: For example, to run the **Get-ServiceLog.ps1** script in the **C:\Scripts** directory, type: "C:\Scripts\Get-ServiceLog.ps1." 92 | 93 | * **All** fenced code blocks must have an approved language tag. For a list of support language tags, see [How to include code in docs](./code-in-docs.md#supported-languages). 94 | 95 | ## Placeholders 96 | 97 | In paragraph text or procedural steps, use italic for placeholder text that users will substitute with their own information. 98 | 99 | - **This**: Enter *password* 100 | 101 | - **Not this**: Enter "password" 102 | 103 | - **This**: Enter **-p** *password* 104 | 105 | - **Not this**: Enter **-p** password 106 | 107 | If you want the user to replace part of an input string with their own values, use placeholder text marked off by angle brackets (less than `<` and greater than `>` characters). 108 | 109 | **Option 1:** Use code-styling to surround the placeholder word or the encompassing phrase. For example, you can use single backticks \` for inline-code formatting for a single phrase, or triple-ticks \`\`\` for code-fenced formatting. 110 | 111 | ```markdown 112 | `az group delete -n ` 113 | ``` 114 | 115 | Rendered as: 116 | > `az group delete -n ` 117 | 118 | or 119 | 120 | **Option 2:** Use a backslash character `\` to escape the angle bracket characters in Markdown, such as `\<` and `\>`. While only the first escape on the left angle bracket `\<` is required, escaping the closing bracket `\>` works too for consistency. The rendered HTML doesn't show the escape character to the reader: 121 | 122 | ```markdown 123 | az group delete -n \ 124 | ``` 125 | 126 | Rendered as: 127 | > az group delete -n \ 128 | 129 | 130 | **Inform the reader about the placeholder**: In the text that precedes placeholder examples, explain to the reader that the text in brackets must be removed and substituted with real values. We recommend the use of italics for user input. You can format italics within angle bracketed inline code: 131 | 132 | > In the following example, replace the placeholder text *``* with your own resource group name. 133 | 134 | > [!CAUTION] 135 | > The Microsoft Learn site does not render \ text that uses angle brackets in cases where the brackets are not escaped properly or the text is not code-formatted. The Microsoft Learn build process interprets the \ phrase as an HTML tag that could be dangerous to the reader's browser, and flags it as a *disallowed-html-tag*. You'll see a suggestion in the build report, and the placeholder word isn't rendered in the Microsoft Learn page output when that happens. 136 | > 137 | > To avoid content loss on placeholders, use `code` formatting or escape characters (`\<` `\>`) as described previously. 138 | 139 | We discourage using curly braces { } as syntactical placeholders. Readers can confuse curly brace placeholders with the same notation used in: 140 | 141 | * Replaceable text 142 | * Format strings 143 | * String interpolation 144 | * Text templates 145 | * Similar programming constructs 146 | 147 | **Casing and spacing**: You can separate placeholder names with hyphens ("kebab case") or with underscores, or you can do it by using Pascal case. Kebab case might generate syntax errors, and underscores could conflict with underlining. Use of all caps can conflict with named constants in many languages, though it may also draw attention to the placeholder name. 148 | 149 | > *``* or *``* 150 | 151 | ## Headings 152 | 153 | Don't apply an inline style like italic, bold, or inline code style to headings. 154 | 155 | **Why?** Headings have their own styles, and mixing other styles creates inconsistencies. 156 | 157 | - **This**: Import the Microsoft.NET.Sdk.Functions package 158 | 159 | - **Not this**: Import the *Microsoft.NET.Sdk.Functions* package 160 | 161 | ## Link text 162 | 163 | Don't apply inline style like italic or bold to link text. 164 | 165 | **Why?** People rely on standard hyperlink text to identify text elements as clickable links. Styling a link as italic, for example, can obscure the fact that the text is a link. 166 | 167 | - **This**: The NuGet package [Microsoft.NET.Sdk.Functions](https://www.nuget.org/packages/Microsoft.NET.Sdk.Functions) generates the function.json file. 168 | 169 | **Not this**: The NuGet package *[Microsoft.NET.Sdk.Functions](https://www.nuget.org/packages/Microsoft.NET.Sdk.Functions)* generates the function.json file. 170 | 171 | ## Keys and keyboard shortcuts 172 | 173 | When referring to keys or key combinations, follow these conventions: 174 | 175 | * Capitalize the first letter of key names. 176 | * Surround the key names with `` and `` HTML tags. 177 | * Use "+" to join keys that the user selects at the same time. 178 | 179 | ### Examples of keys and keyboard shortcuts 180 | 181 | * **This**: Select Alt+Ctrl+S. 182 | * **Not this**: Press **ALT+CTRL+S**. 183 | * **Not this**: Hit `ALT+CTRL+S`. 184 | 185 | ## Exceptions 186 | 187 | Consistent style guidelines create a reliable customer experience and simplify the authoring process. Exceptions to these guidelines must be considered carefully. 188 | 189 | If the exception involves using an alternate text style that normally calls for code, make sure it's OK to translate the text in localized versions of the article. For scenarios where you want to prevent localization without using code style, see [Non-localized strings](/contribute/content/markdown-reference). 190 | -------------------------------------------------------------------------------- /Contribute/docfx.json: -------------------------------------------------------------------------------- 1 | { 2 | "build": { 3 | "markdownEngineName": "markdig", 4 | "content": [ 5 | { 6 | "files": [ 7 | "**/*.md", 8 | "**/*.yml" 9 | ], 10 | "exclude": [ 11 | "**/obj/**", 12 | "**/includes/**", 13 | "README.md", 14 | "LICENSE", 15 | "LICENSE-CODE", 16 | "ThirdPartyNotices" 17 | ] 18 | } 19 | ], 20 | "resource": [ 21 | { 22 | "files": [ 23 | "**/*.png", 24 | "**/*.jpg", 25 | "**/*.gif", 26 | "**/*.pdf", 27 | "**/*.pptx" 28 | ], 29 | "exclude": [ 30 | "**/obj/**", 31 | "**/includes/**" 32 | ] 33 | } 34 | ], 35 | "overwrite": [], 36 | "externalReference": [], 37 | "globalMetadata": { 38 | "breadcrumb_path": "~/breadcrumb/toc.yml", 39 | "contributors_to_exclude": ["Jim-Parker"], 40 | "titleSuffix": "Contributor guide", 41 | "searchScope": ["Contribute"], 42 | "hideScope": false, 43 | "feedback_system": "Standard", 44 | "feedback_help_link_url": "https://learn.microsoft.com/answers/", 45 | "feedback_help_link_type": "get-help-at-qna", 46 | "author": "carlyrevier", 47 | "ms.author": "cahublou", 48 | "ms.service": "learn", 49 | "ms.topic": "contributor-guide", 50 | "ms.custom": "external-contributor-guide", 51 | "uhfHeaderId": "MSDocsHeader-Learn" 52 | }, 53 | "fileMetadata": {}, 54 | "template": [], 55 | "dest": "ContributionGuide" 56 | } 57 | } 58 | -------------------------------------------------------------------------------- /Contribute/includes/note-docsitelocfeedback.md: -------------------------------------------------------------------------------- 1 | > [!NOTE] 2 | > Most localized documentation doesn't offer the ability to edit or provide feedback through GitHub. To provide feedback on localized content, use [https://aka.ms/provide-feedback](https://aka.ms/provide-feedback) form. 3 | -------------------------------------------------------------------------------- /Contribute/index.yml: -------------------------------------------------------------------------------- 1 | ### YamlMime:Marketing 2 | title: 'Contribute to Microsoft Learn' 3 | metadata: 4 | title: 'Contribute to Microsoft Learn' 5 | description: 'Contribute to Microsoft Learn to share your knowledge with the world!' 6 | sections: 7 | 8 | #hero 9 | - componentType: hero-learn 10 | supertitle: MICROSOFT LEARN 11 | title: Create, contribute, share 12 | size: large 13 | summary: Become a Microsoft Learn contributor! Create content to inspire and empower others to build brilliant solutions with the Microsoft platform. Everyone is welcome to share their expertise! 14 | heroImage: 15 | componentType: hero-image 16 | lightImageSrc: /Contribute/media/contributor-home-hero-light.png 17 | darkImageSrc: /Contribute/media/contributor-home-hero-dark.png 18 | links: 19 | - componentType: link 20 | url: https://learn.microsoft.com/training/contributor/contribute-docs-browser/?branch=main 21 | text: Join experts and contribute 22 | 23 | #Text section 24 | - componentType: text 25 | title: Choose your contribution journey 26 | 27 | #Small Cards with Image 28 | - componentType: grid 29 | blocks: 30 | - componentType: icon-card 31 | title: Edit documentation 32 | summary: Contribute to Microsoft's world-class documentation. 33 | url: content/how-to-write-overview.md 34 | icon: 35 | componentType: image 36 | src: media/get-started.png 37 | - componentType: icon-card 38 | title: Respond in Q&A 39 | summary: Answer questions to help others learn about Microsoft technologies. 40 | url: https://learn.microsoft.com/answers/questions/ 41 | icon: 42 | componentType: image 43 | src: media/microsoft-qa-icon.png 44 | - componentType: icon-card 45 | title: Create a collection 46 | summary: Share curated experiences with your followers. 47 | url: /contribute/content/collections?branch=main 48 | icon: 49 | componentType: image 50 | src: media/community-perspectives-icon.png 51 | - componentType: icon-card 52 | title: Join the conversation 53 | summary: Connect with other experts in our Tech Community. 54 | url: https://techcommunity.microsoft.com/t5/microsoft-learn/ct-p/MicrosoftLearn 55 | icon: 56 | componentType: image 57 | src: media/tech-community-icon.png 58 | 59 | # Video cards 60 | - componentType: cards 61 | isShadowless: false 62 | title: Learn skills to help you create content and build community 63 | summary: Check out these resources to get started as a contributor to Microsoft Learn. 64 | blocks: 65 | - componentType: card 66 | title: Meta Skills - Contributing to Communities and Careers 67 | summary: "Power up your career by contributing to open-source community projects. Additional resources:" 68 | imageUrl: media/video-meta-skills.png 69 | url: https://learn-video.azurefd.net/vod/player?id=afb384b7-fd83-474d-a3f2-23dfacc127cf 70 | links: 71 | - componentType: link 72 | url: https://www.youtube.com/watch?v=ZQODV8krq1Q 73 | text: "Watch: Contribute to documentation like a Microsoft Learn Insider" 74 | - componentType: card 75 | title: Technical Writing as a Career 76 | summary: Learn how to turn your penchant for technical writing into a full-time career. 77 | imageUrl: media/video-technical-writing.png 78 | url: https://learn-video.azurefd.net/vod/player?id=5c71cd84-b698-41e0-bbf7-d92ca46a60dd 79 | - componentType: card 80 | title: Making Your Content More Discoverable 81 | summary: "Apply these practical tips to help learners find your content. Additional resources:" 82 | imageUrl: media/video-discoverability.png 83 | url: https://learn-video.azurefd.net/vod/player?id=543d7453-8b31-4b53-b2c7-3d0b501693be 84 | links: 85 | - componentType: link 86 | url: /contribute/content/seo-reference 87 | text: "Read: SEO reference guide" 88 | 89 | # Testimonials section 90 | - componentType: testimonials-section 91 | title: Meet inspirational contributors from the community 92 | cards: 93 | - avatarUrl: media/john-aziz.png 94 | componentType: testimonial-card 95 | name: John Aziz 96 | role: Software Engineer 97 | feedback: Contributing helped me improve my writing skills, and it helped me believe in myself more and made me braver. I've been able to meet and collaborate with lots of amazing individuals too. 98 | link: 99 | componentType: link 100 | url: https://techcommunity.microsoft.com/t5/microsoft-developer-community/contributor-stories-john-aziz/ba-p/4098543 101 | text: Read John's story 102 | - avatarUrl: media/kristina-devochko.png 103 | componentType: testimonial-card 104 | name: Kristina Devochko 105 | role: Principal Cloud Engineer 106 | feedback: I gained so much value from this platform as a user, so I knew it would be a great opportunity to contribute back to Microsoft Learn and to the entire community that uses it. 107 | link: 108 | componentType: link 109 | url: https://techcommunity.microsoft.com/t5/azure-developer-community-blog/contributor-stories-kristina-devochko/ba-p/4017860 110 | text: Read Kristina's story 111 | - avatarUrl: media/emad-al-mousa.png 112 | componentType: testimonial-card 113 | name: Emad Al-Mousa 114 | role: IT consultant 115 | feedback: I'm inspired to contribute whenever I see a section that I can enhance. It's exciting to pinpoint the problem and then provide suggested enhancements. 116 | link: 117 | componentType: link 118 | url: https://techcommunity.microsoft.com/t5/azure-developer-community-blog/contributor-stories-emad-al-mousa/ba-p/3918951?wt.mc_id=contributorstories_techcommunity_blog_cxa 119 | text: Read Emad's story 120 | backgroundImage: 121 | lightImageSrc: /media/home-and-directory/section-testimonials_light.jpg?branch=main 122 | darkImageSrc: /media/home-and-directory/section-testimonials_dark.jpg?branch=main 123 | 124 | # Markdown 125 | - componentType: markdown 126 | content: | 127 | [Read more contributor stories](https://techcommunity.microsoft.com/t5/azure-developer-community-blog/bg-p/AzureDevCommunityBlog/label-name/ContributorStories) 128 | 129 | # FAQ section 130 | - componentType: frequently-asked-questions 131 | #layout: horizontal 132 | title: Frequently asked questions 133 | questions: 134 | - question: How do I become a Microsoft Learn contributor? 135 | answer: There's more than one way to become a contributor! While editing documentation is the most popular method, you can also answer questions in Microsoft Q&A, leave feedback on documentation and training content, create a collection of content for others to consume, or file a GitHub issue if you spot problems in open-source product documentation but don't have the tools to fix them yourself. 136 | - question: What accounts do contributors need? 137 | answer: We recommend having a Microsoft Learn account and a GitHub account. A Microsoft Learn account allows you to contribute to Q&A and create collections, while a GitHub account allows you to edit our documentation or file an issue about open-source product documentation. 138 | - question: How do I start contributing to Microsoft Learn documentation? 139 | answer: Check out our contributor guide! Start with the article on [how to get started](https://learn.microsoft.com/contribute/content/?branch=main#how-do-i-start). You'll find a table that guides you to documentation for each contribution type and lists the account you'll need for each option. The contributor guide is your home base for learning how to get up and running as a Microsoft Learn contributor! 140 | - question: Who contributes to Microsoft Learn? 141 | answer: Anyone can contribute to Microsoft Learn. From first-time contributors to Microsoft MVPs, we see a range of experience and skill levels among folks contributing to the platform. 142 | - question: Do I need to be a Microsoft MVP to contribute to Microsoft Learn? 143 | answer: No! You don't need any special credentials or experience to contribute, just a desire to participate in the community. 144 | - question: What's in it for me? 145 | answer: Contributing to Microsoft Learn benefits not only our learners but also YOU! When you edit documentation, your name appears in the list of contributors at the top of the article. Your commits to our GitHub repos will show up in your GitHub commit history, which is a great way to demonstrate your passion for a particular technology while also building your portfolio. For some products, you can earn digital swag too, like badges. 146 | - question: How do I showcase my content? 147 | answer: Our Contributor Showcase program interviews contributors to learn about why they contribute and share their experiences with others. More information about this program is coming soon. 148 | 149 | # social section 150 | - componentType: social 151 | title: Connect with us 152 | links: 153 | - componentType: social-link 154 | url: https://twitter.com/MicrosoftLearn 155 | destination: twitter 156 | - componentType: social-link 157 | url: https://www.linkedin.com/showcase/microsoftlearn/ 158 | destination: linkedin 159 | - componentType: social-link 160 | url: https://aka.ms/MicrosoftLearnNewsletter 161 | destination: website 162 | -------------------------------------------------------------------------------- /Contribute/media/community-perspectives-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/community-perspectives-icon.png -------------------------------------------------------------------------------- /Contribute/media/contributor-home-hero-dark.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/contributor-home-hero-dark.png -------------------------------------------------------------------------------- /Contribute/media/contributor-home-hero-light.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/contributor-home-hero-light.png -------------------------------------------------------------------------------- /Contribute/media/digital-swag-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/digital-swag-icon.png -------------------------------------------------------------------------------- /Contribute/media/emad-al-mousa.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/emad-al-mousa.png -------------------------------------------------------------------------------- /Contribute/media/get-started.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/get-started.png -------------------------------------------------------------------------------- /Contribute/media/john-aziz.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/john-aziz.png -------------------------------------------------------------------------------- /Contribute/media/kristina-devochko.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/kristina-devochko.png -------------------------------------------------------------------------------- /Contribute/media/learning-rooms-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/learning-rooms-icon.png -------------------------------------------------------------------------------- /Contribute/media/microsoft-qa-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/microsoft-qa-icon.png -------------------------------------------------------------------------------- /Contribute/media/shows-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/shows-icon.png -------------------------------------------------------------------------------- /Contribute/media/tech-community-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/tech-community-icon.png -------------------------------------------------------------------------------- /Contribute/media/video-discoverability.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/video-discoverability.png -------------------------------------------------------------------------------- /Contribute/media/video-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/video-icon.png -------------------------------------------------------------------------------- /Contribute/media/video-meta-skills.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/video-meta-skills.png -------------------------------------------------------------------------------- /Contribute/media/video-technical-writing.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/video-technical-writing.png -------------------------------------------------------------------------------- /Contribute/media/virtual-training-days-icon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/MicrosoftDocs/Contribute/951e2a3a35a3bb3a0b1578279dfcd8767d0a3de3/Contribute/media/virtual-training-days-icon.png -------------------------------------------------------------------------------- /Contribute/zone-pivot-groups.yml: -------------------------------------------------------------------------------- 1 | ### YamlMime:ZonePivotGroups 2 | groups: 3 | - id: keyvault-platforms 4 | title: Client platform 5 | prompt: Choose a client platform 6 | pivots: 7 | - id: windows 8 | title: Windows 9 | - id: macos 10 | title: Mac 11 | - id: keyvault-languages 12 | title: Framework 13 | prompt: Choose a framework 14 | pivots: 15 | - id: nodejs 16 | title: Node.js 17 | - id: dotnet 18 | title: ASP.NET 19 | - id: contribute-tools-zone-pivots-os 20 | title: os-zone-pivots 21 | prompt: Choose the OS you'll work in 22 | pivots: 23 | - id: windows-os-pivot-selection 24 | title: Windows 25 | - id: mac-os-pivot-selection 26 | title: macOS & Linux 27 | -------------------------------------------------------------------------------- /LICENSE-CODE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | Copyright (c) Microsoft Corporation 3 | 4 | Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 5 | associated documentation files (the "Software"), to deal in the Software without restriction, 6 | including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, 7 | and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, 8 | subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice shall be included in all copies or substantial 11 | portions of the Software. 12 | 13 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT 14 | NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 15 | IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 16 | WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE 17 | SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Microsoft Learn contributor guide 2 | 3 | This GitHub repository is the source for the pages in the [Microsoft Learn contributor guide](https://learn.microsoft.com/contribute). 4 | 5 | ## Microsoft Open Source Code of Conduct 6 | 7 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). 8 | For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 9 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | ## Security 4 | 5 | Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, which include [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), [Xamarin](https://github.com/xamarin), and [our GitHub organizations](https://opensource.microsoft.com/). 6 | 7 | If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. 8 | 9 | ## Reporting Security Issues 10 | 11 | **Please do not report security vulnerabilities through public GitHub issues.** 12 | 13 | Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). 14 | 15 | If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). 16 | 17 | You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). 18 | 19 | Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: 20 | 21 | * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) 22 | * Full paths of source file(s) related to the manifestation of the issue 23 | * The location of the affected source code (tag/branch/commit or direct URL) 24 | * Any special configuration required to reproduce the issue 25 | * Step-by-step instructions to reproduce the issue 26 | * Proof-of-concept or exploit code (if possible) 27 | * Impact of the issue, including how an attacker might exploit the issue 28 | 29 | This information will help us triage your report more quickly. 30 | 31 | If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. 32 | 33 | ## Preferred Languages 34 | 35 | We prefer all communications to be in English. 36 | 37 | ## Policy 38 | 39 | Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd). 40 | 41 | 42 | -------------------------------------------------------------------------------- /ThirdPartyNotices.md: -------------------------------------------------------------------------------- 1 | # Legal Notices 2 | 3 | Microsoft and any contributors grant you a license to the Microsoft documentation and other content 4 | in this repository under the [Creative Commons Attribution 4.0 International Public License](https://creativecommons.org/licenses/by/4.0/legalcode), 5 | see the [LICENSE](LICENSE) file, and grant you a license to any code in the repository under the [MIT License](https://opensource.org/licenses/MIT), see the 6 | [LICENSE-CODE](LICENSE-CODE) file. 7 | 8 | Microsoft, Windows, Microsoft Azure and/or other Microsoft products and services referenced in the documentation 9 | may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries. 10 | The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks. 11 | Microsoft's general trademark guidelines can be found at https://go.microsoft.com/fwlink/?LinkID=254653. 12 | 13 | Privacy information can be found at https://privacy.microsoft.com/ 14 | 15 | Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents, 16 | or trademarks, whether by implication, estoppel or otherwise. 17 | -------------------------------------------------------------------------------- /ai-navigator/TOC.yml: -------------------------------------------------------------------------------- 1 | - name: Artificial Intelligence (AI) skills navigator 2 | href: index.yml 3 | -------------------------------------------------------------------------------- /ai-navigator/breadcrumb/toc.yml: -------------------------------------------------------------------------------- 1 | items: 2 | - name: Artificial Intelligence 3 | tocHref: /ai/ 4 | topicHref: /ai -------------------------------------------------------------------------------- /ai-navigator/docfx.json: -------------------------------------------------------------------------------- 1 | { 2 | "build": { 3 | "content": [ 4 | { 5 | "files": [ 6 | "**/*.md", 7 | "**/*.yml" 8 | ], 9 | "exclude": [ 10 | "**/obj/**", 11 | "**/includes/**", 12 | "_themes/**", 13 | "_themes.pdf/**", 14 | 15 | "**/docfx.json", 16 | "_repo.en-us/**", 17 | "README.md", 18 | "LICENSE", 19 | "LICENSE-CODE", 20 | "ThirdPartyNotices.md", 21 | "SECURITY.md" 22 | ] 23 | } 24 | ], 25 | "resource": [ 26 | { 27 | "files": [ 28 | "**/*.png", 29 | "**/*.jpg" 30 | ], 31 | "exclude": [ 32 | "**/obj/**", 33 | "**/includes/**", 34 | "_themes/**", 35 | 36 | "_themes.pdf/**", 37 | 38 | "**/docfx.json", 39 | "_repo.en-us/**" 40 | ] 41 | } 42 | ], 43 | "overwrite": [], 44 | "externalReference": [], 45 | "globalMetadata": { 46 | 47 | "breadcrumb_path": "/ai/breadcrumb/toc.json", 48 | "feedback_system": "Standard", 49 | "permissioned-type": "public", 50 | "uhfHeaderId": "ai" 51 | }, 52 | "fileMetadata": {}, 53 | "template": [], 54 | "dest": "ai-navigator" 55 | } 56 | } 57 | -------------------------------------------------------------------------------- /ai-navigator/index.yml: -------------------------------------------------------------------------------- 1 | ### YamlMime:FAQ 2 | metadata: 3 | title: "AI Skills Navigator: FAQ" 4 | description: "A Frequently Asked Questions (FAQ) page for the AI Skills Navigator." 5 | author: bmackinney 6 | ms.author: miriam.brady 7 | ms.service: artificial-intelligence 8 | ms.topic: faq #Don't change. 9 | ms.date: 10/03/2024 10 | 11 | title: "AI Skills Navigator: FAQ" 12 | 13 | sections: 14 | - name: What is the AI Skills Navigator? 15 | questions: 16 | - question: What is the AI Skills Navigator? 17 | answer: | 18 | The Skills for Social Impact team is building an AI Skills Navigator, an AI assistant designed to direct learners to learning pathways and resources. Users will provide information about their role, expertise level and what they are interested in learning and the navigator will recommend learning pathways. Alternatively, there will be an option to simply ask the AI Skills Navigator a question and it will leverage the skilling pathways and resources it has in its data set to respond or recommend learning. 19 | 20 | - question: What can the AI Skills Navigator do? 21 | answer: | 22 | The AI Skills Navigator, through AI technology, surfaces answers to questions and suggested learning paths based on input from a learner. These are based on a library of learning paths developed by Microsoft and its partners. 23 | 24 | - question: What is/are the AI Skills Navigator’s intended use(s)? 25 | answer: | 26 | The intended use of the AI Skills Navigator is to surface learning paths or information from those learning paths that are most relevant to the learner based on their input with the intention to help the learner gain skills in AI. This is done through an AI-powered assistant. 27 | 28 | - question: How was the AI Skills Navigator evaluated? What metrics are used to measure performance? 29 | answer: | 30 | The AI Skills Navigator has been tested manually and evaluated qualitatively by multiple human testers and subject matter experts, both inside and outside the organization. All grounding data is publicly available and vetted by a Microsoft content team. More evaluation was performed over custom datasets for offensive and malicious prompts (user questions) and responses. In addition, the AI Skills Navigator is continuously evaluated by human testers to ensure it continues to perform at expected levels. 31 | 32 | - question: What are the limitations of the AI Skills Navigator? How can users minimize the impact of the AI Skills Navigator’s limitations when using the system? 33 | answer: | 34 | The AI Skills Navigator is focused on surfacing resources for gaining AI skills. Therefore, users should focus their questions to the AI assistant on that subject area. It will not be able to answer questions related to other subject areas. 35 | 36 | - question: What operational factors and settings allow for effective and responsible use of the AI Skills Navigator? 37 | answer: | 38 | The system does not allow customization. Users should leverage their browser settings to ensure the best experience for this site and others. 39 | 40 | - question: What data is collected by the AI Skills Navigator? 41 | answer: | 42 | The only data collected by the AI Skills Navigator is the information users enter into the chatbot. This data is used for training for the AI and will not be used for any other purpose. 43 | --------------------------------------------------------------------------------