Fix a markdown syntax errors, typos, grammatical errors, and stylistic mistakes

[skycommand]

This PR fixes markdown syntax errors, typos, grammatical errors, and stylistic mistakes in the following files:

Resolve-Windows-Upgrade-Errors.md

Changes in this file are relatively minor. This file uses backslashes instead of parentheses. For example: "\Level 300\" instead of "(Level 300)"

SetupDiag.md

This file has much bigger problems.

Duplicate examples

The Examples section contains duplicate entries. The following diagram shows the problem.

Other grammatical, stylistic, and markdown syntax fixes

• Example of grammatical errors: "sources files" instead of "source files"

• Example of markdown syntax errors: %SystemDrive%\$Windows.~bt\Sources must be wrapped between backticks to avoid \$ being parsed as a Markdown artifact. The following screenshot shows the result of not adhering to this rule:

  

  Please notice the missing backslash.

• Example of technical errors: "Displays interactive help" is wrong because the help displayed isn't interactive.

• Example style and discourse errors: The "Using SetupDiag section" suffers from wrong indentation, a broken list, and orphaned sentences. The following diagram shows the problem.

  

Log-Files.md

• Fix the spelling of "downlevel"
• Add missing commas
• Add missing definite articles
• Change "extend" to "extended"
• Capitalize "Notepad"

Submit-errors.md

Problem 1: The article was written with the following assumptions:

• Windows 10 is the latest version of Windows
• Windows 8.1 is still supported

Neither is true. Windows 8.1 isn't supported. Support for Windows 10 ends in less than a year. People had 12 years to upgrade from Windows 8 to Windows 10.

Problem 2: The user only needs to fill three sections, not four. The "similar feedback" section contains no forms to fill out.

[learn-build-service-prod]

Learn Build status updates of commit c83ab0f:

✅ Validation status: passed

File	Status	Preview URL	Details
windows/deployment/upgrade/resolve-windows-upgrade-errors.md	✅Succeeded
windows/deployment/upgrade/setupdiag.md	✅Succeeded

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 cbc0a5f:

✅ Validation status: passed

File	Status	Preview URL	Details
windows/deployment/upgrade/resolve-windows-upgrade-errors.md	✅Succeeded
windows/deployment/upgrade/setupdiag.md	✅Succeeded

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 c522271:

✅ Validation status: passed

File	Status	Preview URL	Details
windows/deployment/upgrade/log-files.md	✅Succeeded
windows/deployment/upgrade/resolve-windows-upgrade-errors.md	✅Succeeded
windows/deployment/upgrade/setupdiag.md	✅Succeeded

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 4d132f6:

✅ Validation status: passed

File	Status	Preview URL	Details
windows/deployment/upgrade/log-files.md	✅Succeeded
windows/deployment/upgrade/resolve-windows-upgrade-errors.md	✅Succeeded
windows/deployment/upgrade/setupdiag.md	✅Succeeded
windows/deployment/upgrade/submit-errors.md	✅Succeeded

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 1084c2e:

✅ Validation status: passed

File	Status	Preview URL	Details
windows/deployment/upgrade/log-files.md	✅Succeeded
windows/deployment/upgrade/resolve-windows-upgrade-errors.md	✅Succeeded
windows/deployment/upgrade/setupdiag.md	✅Succeeded
windows/deployment/upgrade/submit-errors.md	✅Succeeded
windows/deployment/upgrade/windows-error-reporting.md	✅Succeeded

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

[frankroj]

Thank you for your contribution @skycommand. There are several valid edits in this PR, but there also many unneeded or incorrect edits. A few examples include trying to grammatically fix actual log entries (we include log entries exactly as shown in the logs and not how they should be grammatically correct in the logs), removing some text that changes context (specifically calling out to use the latest version of SetupDiag when MANUALLY running it - when it automatically runs it just uses whatever version is built into Windows and you can't specify to use a newer version), and in your notes mentioning non-existent problems (talking about Windows 8.1 being out of support when the article never mentions Windows 8.1). Trying to fix the numerous issues in this PR would require a lot more work than if I just open a new PR with the valid changes. I can do a new PR, but you wouldn't appear as a contributor in any of the articles. The other option is that I close this PR, and you resubmit the changes via multiple PRs that I can more easily accept/reject (for example, one per article or even better, one per issue).

Remember that we run these articles through a Microsoft approved style and grammatical checker. In other words, some of the items you have changed which you think might be incorrect are actually ok with the Microsoft approved checker. One example is "down-level". The Microsoft checker accepts down-level as being correct as either down-level or downlevel. Since both are deemed correct, there is no need to make this change.

Please let me know your thoughts before I close this PR out.

[skycommand]

@frankroj

You wrote:

A few examples include ... removing some text that changes context (specifically calling out to use the latest version of SetupDiag when MANUALLY running it

I did no such thing. Line 32 of setupdiag.md still reads:

> [!IMPORTANT]
>
> Microsoft recommends running the latest version of SetupDiag, available via the following [download link](https://go.microsoft.com/fwlink/?linkid=870142). Running the latest version ensures the latest functionality and fixes known issues.

your notes mentioning non-existent problems (talking about Windows 8.1 being out of support when the article never mentions Windows 8.1).

That's grossly incorrect.

• submit-errors.md incorrectly asserted (old: line 29; new: line 27) that one must download Feedback Hub. I added that Feedback Hub is already included with Windows 10 and 11. It still can be downloaded for Windows Server, though.

• submit-error.md had a paragraph on line 31 about collecting logs from versions of Windows that don't support Feedback Hub. Those versions are 7 and Server 2008 R2. Microsoft supported upgrading them to Windows 8.1, Windows Server 2012 R2, and Windows 10 v1909. All three items are out of support as of October 2023.

  As setupdiag.md says, Microsoft only responds to SetupDiag feedback when the target OS version is still in support. Hence, this paragraph in its entirety is outdated.

• windows-error-reporting.md said "Learn how to review the events generated by Windows Error Reporting when something goes wrong during Windows 10 setup." I removed "10" because its context now applies to Windows 11 and several members of the Windows Server family.

Trying to fix the numerous issues in this PR would require a lot more work than if I just open a new PR with the valid changes. I can do a new PR, but you wouldn't appear as a contributor in any of the articles. The other option is that I close this PR, and you resubmit the changes via multiple PRs that I can more easily accept/reject (for example, one per article or even better, one per issue).

All of those are bad options. The best thing to do here is to use GitHub's code review functionality.

Remember that we run these articles through a Microsoft approved style and grammatical checker.

No, you don't. Microsoft Editor for GitHub was decommissioned in October 2021. I received the notice.

By the way, "Microsoft approved" is a typo. The correct form is "Microsoft-approved." The decommissioned editor would have told you that.

The Microsoft checker accepts down-level as being correct as either down-level or downlevel.

That's not the point. Well-written texts don't use two different variants of the same words haphazardly. Consistency matters. Even Microsoft's manual of style says that.

[frankroj]

Thank you for the reply @skycommand. My purpose here is not to get into any arguments with you, but to get your valid changes into the docs. A few comments:

1. I can assure you that the articles have recently been run through grammar and style checkers. In fact, several of these articles recently received major updates to get rid of outdated references to older out of support versions of Windows and include newer supported versions of Windows. I assume you aren't internal to Microsoft, and if you aren't, you are probably not familiar with all of the tools we use internally. I agree it wasn't Microsoft Editor for GitHub, but we do have other tools that do review for Microsoft approved style and grammar. I can assure you that the articles have been run through those tools. If those tools are ok with the current grammar and style, then that is what we measure by. If you are internal, reach out to me and we can discuss more internally about the tools we use.

2. Note that we run the articles through these checkers, and not the comments in here, which is a much more informal style of writing. I don't think it really matters if I say Microsoft approved or Microsoft-approved in these comments.

3. Regarding your edit in line 32 about running the latest version of SetupDiag, there is no mention of only doing this when running SetupDiag manually. You removed the context of only doing when running SetupDiag manually. This is what I was commenting about.

4. In my comments I was just pointing out some examples, but there were several more problems with your edits, so much so that it got to the point that there were probably more things to reject than to accept. When it got to that point, I felt it was better to start over than to try to use the review functionality of GitHub. Please note that several of your edits also had to do with style and how something looked, and not that there was necessarily anything wrong with the existing content. In my opinion, we should be concentrating mainly on things that are grammatically or technically incorrect.

5. Regarding Windows 8.1, I was looking for specific instances of Windows 8.1 being mentioned, which I didn't find. Your initial comments in the PR didn't elaborate on this, so I assumed you meant that there were specific references to Windows 8.1. Your comments above clears that point. Thank you for clarifying.

6. I agree on consistency, but with the number of docs in Microsoft documentation written by many different authors and also contributed by the community (such as yourself), there are going to be inconsistencies. As long as it is consistent within the article or across a specific product, that is probably good enough. Trying to look for and find minor inconsistencies like this across a whole doc set is an almost impossible task, and honestly, irrelevant.

We always appreciate community contribution, but in the future, I would recommend making edits like this at a smaller scale, for example one PR per article, so that we can better work with you when edits are needed.

[skycommand]

Hello again, @frankroj. I respect your decision not to become argumentative, so I'll focus on the main points.

1. Redundancy vs. context: This isn't the first time I have edited something and the writer felt I've removed the context. The most recurring instance is the word "successfully," e.g., in "the student graduated successfully in 1994." Sometimes, the writer objects to my removal of the word and claims I deleted the core of their message. In response, I invite them to rewrite the sentence with the opposite adverb. "The student graduated unsuccessfully" is patent nonsense. Upon seeing this hilarious sentence, most writers realize that "graduate" was the core of their message, not "successfully."

   The same applies here. Let me rewrite the original in the active voice so that you can better see the problem: "When you run SetupDiag manually, Microsoft recommends you run the latest version of SetupDiag." As you can see, "manually" is redundant because by definition, "manually" refers to a process that starts at users' discretion. Remove "manually," and you'll end up with "When you run SetupDiag, Microsoft recommends you run the latest version"!

   You see, the context you claimed I removed was not in the word "manually," but in "Microsoft recommends running." The latter implies a manual execution on which the user has control.

2. Consistency: Spelling inconsistencies on the same page instill distrust in the reader. I've seen it firsthand in academic environments. When establishing cross-project consistency isn't feasible, it is still prudent to establish local consistency. I saw "down-level" and "downlevel" on the same page, so I fixed them.

3. Microsoft language tooling: The Microsoft Learn website, originally called Microsoft Docs, came into being after Microsoft realized that its command of the English language was far from perfect despite whatever software tooling the company has in place. I assure you, you'll move on from this job (hopefully to something better) long before the tooling reaches perfection.

4. Required commitment: If you think I have more mistakes, please point them out. I came here to improve these articles, not to receive general feedback on my writing skills. I have much confidence in the latter and for good reasons too.

[frankroj]

Thanks again @skycommand for the feedback.

1. We were purposeful in adding "manually" in for context. We have to balance "grammatically correct" with what will minimize or avoid support calls. You actually call out the problem with removing "manually" - it is implied but not actually specified. Sometimes we have to be very specific about a scenario and not assume that the customer is going to assume the same thing as us. If we don't specifically put in "manually" into the sentence, then that will start generating calls with customers asking how they can use the latest version SetupDiag when it runs automatically, and that is what I am trying to avoid. I spent 14 years in Microsoft support, and I have seen countless instances where when the docs are not very specific at something and spell it out in detail, it generates calls and cases. What we assume isn't always what the customer assumes.

2. If there are instances of both down-level and downlevel in this article, the I agree with you. My concern though is there are more instances of this throughout the doc set, and I don't want it to become an even bigger project that what it already is. I can look over these set of articles and make it consistent in these set of articles. However, this was just one example. Another example is where you asking to change the "Levels" from slashes to parentheses. I agree with you here and don't know why the original author chose slashes, but the problem is that this notation is used throughout the doc set. From your own suggestion of being consistent, I want it to be consistent throughout the doc set without this becoming a much bigger project.

3. I'm not sure if you're reasoning for the rebranding of Microsoft Learn is accurate, nor do I know where you are getting that info from. Regardless, it's irrelevant and a moot point. And regarding my career at Microsoft, I've been at Microsoft for 16 years and most likely will retire in my current role (where I am happy at), so who knows if I will ever see the tooling perfected (is any tool ever perfect?)

4. My feedback isn't on your writing skills, but on some of the specific edits you have done. I am sure you are great writer, and it shows from some of the edits you have done. However, part of my job is to review contributions. My background is technical and support, and not writing, but I was purposely hired into the role because of my technical background. Sometimes with the technical background you see problems in docs that a purely grammatically correct writer won't see, for example the "manually" edit discussed above.

Part of the problem with this PR is that community contributions are usually small in scale limited to one article, so can usually be easily and quickly reviewed. If changes are needed, it is easily handled because it's usually only one (or a few) changes. With this PR, there are many contributions across several articles, several which need to be removed or changed. Can I do it via reviews? Sure, but it is low priority for me because I have several other big projects that I am working on right now that have much higher priority, especially since several of these articles were recently updated. If you want, I can keep this PR open and I will eventually do the reviews, but it will be some time before I can get to it. I can't give you a specific time frame. My suggestion to you break up the edits to more PRs was so that I could maybe at least get some of the edits approved sooner vs. later, but with everything being in one PR, it's all or nothing. The easiest thing for me to do is just do the edits I agree with in a new PR, but I know this takes credit away from you and we always like contributors to get the credit. I don't want to discourage you from making many edits, which again is greatly appreciated and encouraged, but just suggesting how you can better work with us in the future to getting things approved quicker.

[skycommand]

@frankroj I've been working in IT for 26 years now. I have done support jobs, helpdesk jobs, dev jobs, admin jobs, cabling jobs, and sometimes a janitor's job just so unqualified personnel don't ruin our pricy equipment.

As such, I'm familiar with the "we get support calls if we do such-and-such" kind of reasoning. The truth is, you'll get support calls regardless of the quality of your work. That's a good thing because it means people care. Also, my work experience says the only support calls you'll ever get for the change in line 34 of SetupDiag.md are congratulatory ones.

I've done large PRs for Microsoft. Sean Wheeler and I once worked on the about_Comparison_Operators. Despite its immense scope, we completed it because Sean didn't stall. In comparison, this PR is small; it consists of five tiny pages. And we're on the sixth round of conversation, but you haven't started any reviewing. If you have other Microsoft priorities, do either of the following:

• Attend to them. It's not like I can pressure you for time. We can postpone this to whenever you're ready to commit yourself.
• Trust me and commit the PR. I'm not some random kid on the Internet. My GitHub account's history speaks for itself.

The more you delay, though, the longer this repo remains in the pathetic state shown in this screenshot:

[learn-build-service-prod]

Learn Build status updates of commit 3bc3e32:

✅ Validation status: passed

File	Status	Preview URL	Details
windows/deployment/upgrade/log-files.md	✅Succeeded
windows/deployment/upgrade/resolve-windows-upgrade-errors.md	✅Succeeded
windows/deployment/upgrade/setupdiag.md	✅Succeeded
windows/deployment/upgrade/submit-errors.md	✅Succeeded
windows/deployment/upgrade/windows-error-reporting.md	✅Succeeded

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

[frankroj]

Sorry @skycommand but my job isn't just to blindly trust. Just the opposite - these being public facing customer docs I have to closely review everything. I've already done some preliminary reviews and just don't agree with some of the changes you have made. I don't agree with your assessment that the articles are in a pathetic state. They were in a very bad state a few months ago and very out of date, but the work was done to get them up to date. I am sorry they are not at the state that you would like or that you would expect. However, because they were recently updated and generally in good shape, this is very low priority. We can agree to disagree and that's fine, but ultimately it is my judgement call.

This is not a small customer submitted PR. It's the largest one I have ever seen and the first one ever that I have seen involving multiple articles. My suggestion to you regarding making smaller PRs is so that this process can go more smoothly in the future. You can choose to take my advice or leave it. You are right that I have probably now spent more time going back and forth with you on this than if I had just reviewed it in the first place. I didn't expect to get so much pushback from you and have to go back and forth with you justifying my decisions. For this reason, what I can just simply state is a commitment to review the articles more in depth in the future and provide the reviews you requested, but I can't spend any more time discussing this with you here. Again, we appreciate your contributions and I definitely agree with some of the changes you have made, but the problem is that I don't agree with all of them, and that is where some time-consuming work and review will need to take place.

[skycommand]

Alright, let's review all your standing objections to my PR so far:

• There are problems with my PR that you won't tell me: The world is familiar with this form of smear tactic. GitHub is a place to identify, mark, negotiate, and root out problems, and you're not doing those.
• Because of time, you cannot prioritize this PR: That would justify a delay in your response, but not everything else you've said and done, including assigning this PR to yourself.
• You are worried about customer reaction: This is a customer reaction! You don't think I'm your CEO, do you? No. I represent IT pros, the main customers, and the readership of these documents. If you can afford to treat me so poorly, you can do the same to your imaginary customers. Tell them their complaint has a problem that you won't tell!
• This PR is "not small": Let's assume it is. Big problems demand big PRs and a good PR maintains cohesion across multiple documents. I'm the one who did the heavy lifting anyway.

I know what's your real problem, though. The size and quality of my changes threaten you. That's why you picked it up in the first place. You intended to close it. Your first message says as much.

It isn't too late to turn back. I appeal to all the good left in you to do an actual review of my PR and work with me to resolve whatever actual problem you may find. Do that and the unpleasant conversation we've had so far will soon be forgotten. If you're worried about your position within Microsoft, 26 years of experience tells me only good comes from fidelity and integrity.

[skycommand]

I updated the screenshot #2 with better markup.

[aczechowski]

The Microsoft Open Source Code of Conduct, which outlines the expectations for community interactions in and around docs.microsoft.com, is designed to help "provide a welcoming and inspiring community for all." The content of this issue appears to be out of sync with the code of conduct, so we have closed it.

I've opened an internal task in Azure DevOps (9046465) for Frank to review your feedback and incorporate as needed into these articles.

[skycommand]

@aczechowski I came here with the best intentions and made a good-faith effort to contribute as part of a community. My goal was to make the pertaining documentation a valuable resource for IT pros. Frank lied to me, insulted me, and wasted my time at the cost of indignifying every IT pro on this planet. No amount of CoC and CLA can justify that.

I'm disappointed in Frank ... and you.