MicrosoftDocs / PowerShell-Docs

The official PowerShell documentation sources
https://learn.microsoft.com/powershell
Creative Commons Attribution 4.0 International
1.96k stars 1.56k forks source link

Adds reference docs links, formatting and refactoring test performance test #11077

Closed santisq closed 3 months ago

santisq commented 3 months ago

PR Summary

This PR adds many reference links to PowerShell and .NET docs. I'm not sure if the links are correct, please let me know if they should be fixed, I've basically removed https://learn.microsoft.com/en-us from them and made them relative hope that's right.

There are also many formatting changes and also updated the performance tests for Avoid repeated calls to a function to have the same format as the previous tests.

As aside, I feel that Avoid Write-Host should be removed or rewritten. Haven't removed it in this PR but if you feel the same I can open an issue / make a new PR for that. After discussing it in the pwsh Discord the conclusion was that the recommendation is misleading. The usage of static methods from System.Console can be confusing specially for new folks and shouldn't be part of this doc, and the recommendation to use Write-Output instead of Write-Host is also incorrect, first, the explicit usage of Write-Output is not needed to begin with and is only useful when preventing pipeline enumeration with -NoEnumerate or for unrolling a collection i.e.: , (0..10) | Write-Output | ForEach-Object { "[$_]" } vs , (0..10) | ForEach-Object { "[$_]" } and second, the purpose of Write-Host is to send information directly to the console and prevent it's output to be captured by default. So if the intent is to offer a better cmdlet for this purpose, a better recommendation would be to use Write-Verbose instead of Write-Host ?

PR Checklist

learn-build-service-prod[bot] commented 3 months ago

Learn Build status updates of commit 65c0978:

:white_check_mark: Validation status: passed

File Status Preview URL Details
reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md :white_check_mark:Succeeded View (>=powershell-5.1)

For more details, please refer to the build report.

For any questions, please:

github-actions[bot] commented 3 months ago

Expectations

Thanks for your submission! Here's a quick note to provide you with some context for what to expect from the docs team and the process now that you've submitted a PR. Even if you've contributed to this repo before, we strongly suggest reading this information; it might have changed since you last read it.

To see our process for reviewing PRs, please read our editor's checklist and process for managing pull requests in particular. Below is a brief, high-level summary of what to expect, but our contributor guide has expanded details.

The docs team begins to review your PR if you request them to or if your PR meets these conditions:

You can always request a review at any stage in your authoring process, the docs team is here to help! You do not need to submit a fully polished and finished draft; the docs team can help you get content ready for merge.

While reviewing your PR, the docs team may make suggestions, write comments, and ask questions. When all requirements are satisfied, the docs team marks your PR as Approved and merges it. Once your PR is merged, it is included the next time the documentation is published. For this project, the documentation is published daily at 3 p.m. Pacific Standard Time (PST).

learn-build-service-prod[bot] commented 3 months ago

Learn Build status updates of commit 8d18965:

:white_check_mark: Validation status: passed

File Status Preview URL Details
reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md :white_check_mark:Succeeded View (>=powershell-5.1)

For more details, please refer to the build report.

For any questions, please:

sdwheeler commented 3 months ago

I did some minor editing to conform to our style guidelines and updated the notes about Write-Host.

learn-build-service-prod[bot] commented 3 months ago

Learn Build status updates of commit 25d2f09:

:white_check_mark: Validation status: passed

File Status Preview URL Details
reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md :white_check_mark:Succeeded View (>=powershell-5.1)

For more details, please refer to the build report.

For any questions, please:

learn-build-service-prod[bot] commented 3 months ago

Learn Build status updates of commit dcd1947:

:warning: Validation status: warnings

File Status Preview URL Details
reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md :warning:Warning View (>=powershell-5.1) Details

reference/docs-conceptual/dev-cross-plat/performance/script-authoring-considerations.md

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

For any questions, please: