Windowsserverdocs: Standalone server Storage Spaces PowerShell deployment documentation is woefully lacking important details

[jdrch]

While the prose explanation of Storage Spaces is decent, the documentation for the PowerShell commands is horrifically bad. This is important because the Windows 10 Storage Spaces GUI often fails to create pools on eligible drives, leaving PowerShell as the only option.

Here's a short list of the critical details missing:

1. How to prepare disks for Storage Pools. Contrary to what the docs page would have you believe, it is NOT sufficient just to format the target drives. They have to reset in PowerShell using Reset-PhysicalDisk, and then the host machine needs to be rebooted to ensure the reset takes
2. The –StorageSubsystemFriendlyName value is obtained from the OS and not supplied or generated by the user! This isn't EVEN REMOTELY obvious in the documentation. The value is discovered by running Get-StorageSubsystem. Why would you leave this critical detail out?

Without knowledge of the above 2 points, which are not described in detail or even referenced anywhere on the page, a user attempting to follow instructions will meet certain failure.

This is extremely disappointing, poor documentation for a 1st class Windows feature. Please do better.

I've done some of the work for you and written a clear, step-by-step process on how to get it done, with gasp nothing omitted.

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: b5eff1fc-f935-23b3-6165-914061f81334
• Version Independent ID: 6689ae37-f31e-ec5d-f964-5695a5a6dc14
• Content: Deploy Storage Spaces on a stand-alone server
• Content Source: WindowsServerDocs/storage/storage-spaces/deploy-standalone-storage-spaces.md
• Product: windows-server
• Technology: storage-spaces
• GitHub Login: @JasonGerend
• Microsoft Alias: jgerend

[illfated]

Thank you for the feedback. That looks like quite good work and insight into the material in question.

Disclaimer: I am not affiliated with Microsoft or the Microsoft Docs teams here on GitHub.

Seeing how well you manage your own material, would you be interested in creating a PR to have this page updated correctly?
(I mean, I could try to do it, but I might not get the intended content order correct at my first attempt.)

Just in case you did not know: the MS Docs team members might not have time to answer your question, both due to the small size of the team and the big workload.

[jdrch]

Thank you for the feedback. That looks like quite good work and insight into the material in question.

You're welcome. Apologies for the tone; I was super frustrated at something that should have taken 15 minutes taking instead hours to figure out.

Seeing how well you manage your own material

Thanks, I try. I created that repo to keep track of my hardware configs and associated issues as well as to not have to rely on memory to resolve issues.

would you be interested in creating a PR to have this page updated correctly?

Sounds like a good idea. I'll get to it after I complete the ReFS volume on Storage Spaces setup. So far "all" I've been able to manage is to create the Storage Pool. Gonna read some more documentation to make sure I'm not missing anything else.

I might not get the intended content order correct at my first attempt.

I get the distinct impression the docs weren't written by anyone who'd actually implemented SS, so your PR might not be further off than they are :P

Just in case you did not know: the MS Docs team members might not have time to answer your question, both due to the small size of the team and the big workload.

Fair enough, but if they don't have the time to answer a question, how are they going to find time to merge a PR? Just asking 🤔

[illfated]

Thanks for the detailed reply. Well, the way I see it, it is usually much less formal work involved in merging a PR, as long as the PR gets approved by the current author (or rather "author only by virtue of job position", because the original author might be retired from their original job position or moved on to an different department entirely).

Following up a question usually involves contacting one of the few remaining team members, whose job it usually is to work on improving the documentation by also communicating with internal contacts within the Microsoft organization, but in case of needing to answer the technical question, it needs to be a qualified answer verified internally so it does not reflect negatively on Microsoft as such.

The team members who regularly review and merge PRs from external contributors are usually the same members who also review and merge contributions provided by Microsoft employees by using the private (hidden) parts of the repository, only accessible and readable for Microsoft Docs (organization) members here on GitHub.

If I were you, I would focus primarily on setting up a PR with the obviously most needed changes, keeping it clear that the content is straight forward and comparable to the existing document. If you are able to add some information as proof or basis for your PR, that would be even more helpful to get a quick review and feedback faster than a mere question ticket here in the issue pages will get you.

Feel free to browse through and take a glance at my existing & merged PRs, if you want to get a feel for what I believe a good PR should include.

[jdrch]

Appreciate the explanation!

Feel free to browse through and take a glance at my existing & merged PRs, if you want to get a feel for what I believe a good PR should include.

Will do!

[illfated]

By the way, if the Microsoft Docs pages were only visited by IT Pros familiar with the use of GitHub and various git applications (command-line or GUI), I would have suggested adding a Pull Request template based on my experience with programming-related repositories here on GitHub. Seeing that the everyday users of this repository may not be too exited to learn how GitHub works internally or which git applications exist to handle pull requests & manage personal repositories, I have put that idea on a very icy shelf for distant future use. 😉

[jdrch]

may not be too exited to learn how GitHub works internally or which git applications exist to handle pull requests & manage personal repositories

Just tell (or link) me (to) what you know; I'll decide how "deep" I want to go. As you've probably already seen, I have quite a few other issues over here to attend to, but I'm not opposed to learning something I can reuse later on.

[illfated]

Well, first of all I like to mirror the content of what the PR comment box should contain by adding the same text in the git commit message. That saves a lot of time when opening a new issue, especially because I am close to autistic when it comes to details (autist per se, but a highly functioning one). My second point on the list is to divide my commit message / PR comment content into separate sections or paragraphs with headings or plain bold text as semi-headings.

I also notice that mostly only those very few users who are very familiar with repository issues and combining pull requests with issue tickets know about the method GitHub allows for automatic closure of tickets, provided this line exists in the commit message (preferably the first commit) looking something like this:

Closes #4612

My habit is to add this line at the end of the commit message, based on my 5+ years long experience from working with issues, PRs and commits in the C++/MySQL coding community TrinityCore.

[jdrch]

All of that sound like good ideas all around. Thanks!

[illfated]

I must admit that I also enjoy using as much as possible of my MarkDown knowledge, even though my experience with MarkDown is shorter than my overall time as a GitHub member.

[jdrch]

MarkDown

That's what I use too. That said, there's a fair amount thereof that GitHub doesn't support (not the last time I checked, at least) such as tables.

[illfated]

MarkDown

That's what I use too. That said, there's a fair amount thereof that GitHub doesn't support (not the last time I checked, at least) such as tables.

Well, that is more or less true, at least to some extent. There are variants of MD tables, based on MarkDown spec versions, where some will not render properly on GitHub, but might be translated correctly to HTML, -- while GitHub will support at least one version of MD tables. I don't remember exactly which one, but there are several discussions on Stack Exchange where this has been discussed. If you need to know the version information, I would recommend a web search for "GitHub MarkDown table versions" (or similar), while existing tables should be OK as they are. Please note: Notepad++ may show MD tables as natively MarkDown compatible, but not necessarily the version supported by GitHub.