about_Ref.md: Relationship between [ref] and [PSReference]

[skycommand]

PR Summary

This PR adds a new section, entitled "Relationship between [ref] and System.Management.Automation.PSReference" to the about_Ref.md file for three versions of PowerShell: 7.5, 7.4, and 5.1. This section discusses the fact that PowerShell doesn't treat [ref] and [System.Management.Automation.PSReference] (a.k.a. [PSReference]) semantically the same.

Additionally, this PR changes a "note" box to an "important" box because of the information in that box is "required for user success." See Markdown best practices for their differences.

Minor syntactic changes were made by the Authoring Tools' linter.

PR Checklist

• Descriptive Title: This PR's title is a synopsis of the changes it proposes.
• Summary: This PR's summary describes the scope and intent of the change.
• Contributor's Guide: I have read the contributors guide.
• Style: This PR adheres to the style guide.

[github-actions]

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:

• It is not a draft PR.
• It does not have a WIP prefix in the title.
• It passes validation and build steps.
• It does not have any merge conflicts.
• You have checked every box in the PR Checklist, indicating you have completed all required steps and marked your PR as Ready to Merge.

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).

[sdwheeler]

@skycommand Thanks for pointing out the difference. There are some issues with your description.

• ref is not a keyword in the PowerShell language.
• [ref] is a type accelerator but it does more work than [System.Management.Automation.PSReference], hence the difference. There are two other type accelerators that do extra work: [pscustomobject] and [ordered].
• There is more information that needs to be included in the article. See the summary from this other issue: Restrict use of [ref] to variables PowerShell/PowerShell#6807 (comment)

I am working on an update to your PR so you will still get contributor credit.

[learn-build-service-prod]

Learn Build status updates of commit 6cfa7df:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Ref.md	✅Succeeded	View (powershell-5.1)
reference/7.4/Microsoft.PowerShell.Core/About/about_Ref.md	✅Succeeded	View (powershell-7.4)
reference/7.5/Microsoft.PowerShell.Core/About/about_Ref.md	✅Succeeded	View (powershell-7.5)

For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[learn-build-service-prod]

Learn Build status updates of commit fdac17c:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/5.1/Microsoft.PowerShell.Core/About/about_Ref.md	✅Succeeded	View (powershell-5.1)
reference/7.4/Microsoft.PowerShell.Core/About/about_Ref.md	✅Succeeded	View (powershell-7.4)
reference/7.5/Microsoft.PowerShell.Core/About/about_Ref.md	✅Succeeded	View (powershell-7.5)

For more details, please refer to the build report.

For any questions, please:

• Try searching the learn.microsoft.com contributor guides
• Post your question in the Learn support channel

[skycommand]

@sdwheeler Wow! You really merged it! The whole thing is over in 8 hours. 🙏 Does the entire Microsoft know that you're their most efficient and most pleasant reviewer? I hope they do.

Anyway...

I have some suggestions. In technical writings, we should avoid bloated verb forms and metonymy to reduce wordiness. (We do the opposite in communicative writings such as this one to sound more polite.) "Use X to do Y" is the bloated form of "Do X with Y." Metonymy turns it into "Y does X." For example, "You can take advantage of a script block to initialize variables" becomes "You can initialize variables in a script block" (without metonymy) and "A script block can initialize variables" (with metonymy).

Have a good one. 👍

[sdwheeler]

@skycommand Thanks for the compliments. Regarding the use of metonymy:

We strive for concision but there are several factors that play into how we balance verbosity against concision.

• The direction from our official style guide is to "write how we speak".
• We need to be sure that what we write is accurate and clear; not subject to misinterpretation.
• We need to consider how the English text will get translated to other languages. That often requires more verbosity.

With that said, we aren't perfect writers. There is always room for improvements.

[skycommand]

@sdwheeler Hello, again. Sorry to be a pest, but there are some urgent issues that need fixing. I've highlighted them above.

By the way, do you not receive any notification unless I use an at-mention? I've posted the first comment yesterday, two minutes after you posted your last comment. (You see, in my case, all at-mentions are superfluous. I get a notification for the comment regardless.)

[sdwheeler]

@skycommand After the PR has been merged, it is better to open a new issue for further discussions. I do get notifications, but I may not be able to respond immediately.

FYI - I am officially on vacation for the remainder of the year.