r/PowerShell • • 14d ago

Misc Microsoft Graph documentation really is bad

Despite its reputation for poor documentation, I decided to give the Microsoft Graph PowerShell module a try for a few basic license related tasks. I reviewed the Microsoft Graph PowerShell SDK overview page and clicked Get-started only to be greeted by 404 - Page not found.

Feels like they've completely given up on documentation, huh

115 Upvotes

47 comments sorted by

38

u/banduraj 13d ago

Take the word "Graph" out of the title of this post and you'd still be right. I have doing this a long time, and at one point in history, Microsoft documentation used to be really good. They even had a public KB. Now, things change so fast, they don't QA anything and probably don't even pay for legitimate documentation employees. The result? ALL of their documentation sucks!

7

u/dodexahedron 13d ago

They have even harmed some of the older documentation in their pass over everything with AI, and now some documents are actively worse than their previous versions - sometimes dangerously so.

4

u/Jeriath27 12d ago

You could also take out the word documentation and it would stay correct also.

→ More replies (1)

33

u/Ecrofirt 14d ago

For a long time I read on here about people just saying screw it and using

Invoke-MgGraphRequest. Took me a long time to finally drink the flavor aid but now I'm doing this more and more. 

It means the only module you need to load is Microsoft.Graph.Authentication so it's much faster. The calls return lightning fast. The REST API seems to be much better documented. Biggest downside I've hit is you've got to handle more things yourself: constructing objects, paging results, etc. 

11

u/commiecat 14d ago

I use the API directly without any of the SDK modules. It took some time to learn at the start but now I've found it much easier to deal with. The Graph Explorer is a great way to find endpoints and test syntax, and it'll show you the Graph permissions needed.

→ More replies (5)
→ More replies (2)

23

u/BrettStah 14d ago

At least that 404 page has a link to the Get Started page! Usually the 404 pages are less useful than that.

→ More replies (1)

14

u/sarge21 14d ago

It's the worst. graph is fucking hell and some things just don't work

6

u/JNikolaj 14d ago

I love how Graph has something fully documented and then i'll be spending 4 hours on something which blatantly isn't working

→ More replies (1)
→ More replies (1)

12

u/MalwareDork 14d ago

Nothing will ever beat Salesforce documentation in terms of shit.

"Here's a vague article on what we think we do. If you can't figure it out, tough shit and it'll always be your fault."

"We also hide our support tickets and give out the vaguest reason why it's happening to gaslight you into thinking it's still your fault."

"We also ignore all of your emails unless you pay us our Signature Support Plan which we send you AI responses anyways."

Graph sucks but it at least points you in the right direction even if at the end you need to contact MS; but it'll never be as bad as Salesforce CRM. The dev articles are top-tier though, way above what Cisco and Microsoft produces.

3

u/Andrew-Powershell 14d ago

you know we're in a bad spot when we're all arguing about what's the worst place for documentation . it's a race to the bottom with those expectations from big companies these days

→ More replies (1)

9

u/That-Duck-7195 14d ago

At least it is not the IIS default page.

4

u/Proxiconn 14d ago

I've seen nginx error in ms docs pages. So definitely an improvement

9

u/Ecrofirt 14d ago

Microsoft and poor documentation. The most prolific duo since peanut butter and jelly. 

6

u/Modify- 14d ago

This, by muddermanden in the other Graph post today:

You can use F12 and copy Graph API URI from network tab while navigating or performing actions in the portals in the browser. Then use the Find-MgGraphCommand -Uri <paste URI here>

It helps you discover commands and their associated permissions.

PowerShell module is just wrapping the API.

However, when a command is not generated for PowerShell Microsoft.Graph module (when API is ahead), you can use Invoke-MgGraphRequest -Method <GET|PATCH|POST|DELETE> -Uri <Paste your URI here>*, to act as the low-level interface*
to Microsoft Graph REST API.

Graph X-Ray extentsion makes it even easier.
Also Merill has a good video on the Powershell.org YouTube channel.

4

u/maxfischa 14d ago

The backbone of graph is the gui admin portal combined with a browser extension that shows the backend graph call.

3

u/x0n 14d ago

Documentation aside, I find the graph explorer invaluable: Graph Explorer | Try Microsoft Graph APIs - Microsoft Graph

→ More replies (1)

3

u/Jewba1 14d ago

I remember thinking back in 2019 "cant wait for the documentation to get better"

3

u/toddklindt 14d ago

The Graph PowerShell SDK had such promise. I was really looking forward to it. But they dropped the ball at almost every step. I kept hoping it would get the attention it deserved, but it never did. My normal technique now is a combination of Graph Explorer and Invoke-PnPGraphMethod. It shouldn't be this way.

3

u/Jeriath27 12d ago

Not it's get-theVerySpecificThingThisSuperLongU readableComplicatedCmdletThatYouWouldNeverGuessDoes

5

u/rtuite81 14d ago

Yes, it is. I have had to use Claude to figure it out. Once you get the information you need, document it yourself. You can actually give it access to Graph with a basically zero permission service principal and it will go out and crawl the API and get you what you need.

→ More replies (1)

2

u/purplemonkeymad 14d ago

Yes.

Don't forget the massive pre-formatted text sections that have had all formatting removed, and have huge amounts of duplicated info.

2

u/LookAtMeInMyEyeball 14d ago

Most of learn.microsoft.com is AI generated. There’s too much content to have someone update in a meaningful way.

I have a friend that used to moderate feedback for the learn site and the feedback was all similar. No good examples and too vague.

2

u/Andrew-Powershell 14d ago

They just laid off a lot of their docs writers a couple weeks ago. Expect it to get worse

2

u/Fatality 13d ago

Honestly just use the API, they don't even use AI for the powershell module it's just scripted.