Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The Elephant at WWDC

eclecticlight.co

Post reply on HN
Print view View original

91–100 of 213 posts

Re: The Elephant at WWDC

#91

Post by justinclift »

bob1029 wrote: post #30

Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked. Here's a high level overview of GC to give you an idea of how thorough these documents are now: https://docs.microsoft.com/en-us/dotnet/standard/garbage-col... After reading through all of those sections, I will have develo…

Conversely, when looking through the Azure documentation last week for much of their Python SDK libraries... it's a joke.

They have _tonnes_ of new-user intro stuff and similar. Super impressive at first look, but once you're past that and need to dig into complicated things it's all undocumented.

Even most of the auto-generated pages in their Python SDK function lists are just "Header -> empty space where content should be -> footer". And nothing else.

... and lets not get started on the docs for Microsoft Graph. :/

Re: The Elephant at WWDC

#92

Post by gambiting »

dafelst wrote: post #79
gambiting wrote: post #71

Earlier quoted context omitted.

I'm a games developer working on some AAA xbox productions and I don't think I agree. My #1 impression with Microsoft documentation is that you run into a message "error occurred, click here to open documentation page", you click on it, only to be redirected to a 404 page or simply to MSDN's main website. Like, yes, the pages that exist are usually very well written and detailed. But jesus christ, their links even ju…

Agreed, the Xbox documentation is hot garbage. They expect you to flip flop between the .chm file shipped with the XDK and online, but like you say the links are almost always broken. On the flip side though the private Xbox dev forums are awesome, I find them more useful than the docs. Sony's PS4/PS5 docs also suck and are a giant pain in the ass to get to because they make you allow-list only specific IP addresses…

Yeah, xbox forums are very very good, and you usually get a reply directly from someone on the Xbox Development team within few hours. If you ever get a chance to go to XFest(assuming they still continue after the pandemic), it's really worth going - you get to meet people actually working on the hardware and software, collecting some of their emails goes a long way when working on a game ;-)

And yes, PS4/PS5 documentation is....lacking. It's all in one place and at least easily searchable but most functions have descriptions 2 sentences long and you have to look in the samples for the actual knowledge of how to call something.

Re: The Elephant at WWDC

#93

Post by [deleted] »

smoldesu wrote: post #83
bob1029 wrote: post #30

Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked. Here's a high level overview of GC to give you an idea of how thorough these documents are now: https://docs.microsoft.com/en-us/dotnet/standard/garbage-col... After reading through all of those sections, I will have develo…

I despise Microsoft's products for the most part, but I can't lie: their documentation kicks ass. The C++ documentation is some of the nicest around.

[deleted]

Re: The Elephant at WWDC

#94

Post by the-dude »

moralestapia wrote: post #69

Something I really loathe about OS X, and it has been becoming worse with time, is the amount of "processes" or whatever that suddenly take 100% CPU. There's no place to find out what they are. What are they doing, are they from apple or not? You're hopeless, aside from some comments here and there from random members of the community. To this day, I have no idea what 'powerd' is, for instance.

And you couldn't be bothered to do a cursory search?

> There's no place to find out what they are.

Google worked fine for me. YMMV.

Re: The Elephant at WWDC

#95

Post by sircastor »

LeSaucy wrote: post #82
nextweek2 wrote: post #76

Earlier quoted context omitted.

> Microsoft has had superb documentation for decades No, they've had lot's of documentation. That's not the same thing. For decades it was very shallow with no examples. You'd get an enum list with a half sentence explanation. The last couple of years they've really upped their game. With detailed examples, explanations and even source in multiple languages. To me Qt's documentation was the benchmark, but the latest…

Qt5 documentation quality has steadily slid down hill. Any new modules they add you essentially have to peruse the source to understand what/how/why it works.

I had a coworker critical of my position while working with Qt when I complained about poor documentation, saying that if I needed to know how something worked, I should just read the source.

Re: The Elephant at WWDC

#96

Post by throwaway894345 »

defaultname wrote: post #84
nextweek2 wrote: post #76

Earlier quoted context omitted.

> Microsoft has had superb documentation for decades No, they've had lot's of documentation. That's not the same thing. For decades it was very shallow with no examples. You'd get an enum list with a half sentence explanation. The last couple of years they've really upped their game. With detailed examples, explanations and even source in multiple languages. To me Qt's documentation was the benchmark, but the latest…

"No, they've had lot's of documentation. That's not the same thing. " This kind of snotty reply is always interesting. I've been a professional developer for 25 years. For most of those years I was deep in the Microsoft platform. C++, Win32 API, DirectX, COM+/DCOM, OLE, automation, C# / .NET. For decades they've had exhaustive narrative documentation that would give huge backgrounders on everything. Architectural "ho…

> This kind of snotty reply is always interesting. I've been a professional developer for 25 years.

I didn't interpret it as "snotty" (not beyond the norm for this forum, anyway). Could have been worded better, but charitable interpretation is an HN guideline.

> There is some bizarre tendency in here for people to pretend that everything Microsoft does well they've only done well for most recent history, as if this is some sort of odd proselytizing and naysayers should realize that everything has changed.

Or perhaps the parent just disagrees with you on merit and there is no nefarious underlying motive? In my experience at least, Microsoft's ethos and behavior has improved significantly in the last ~decade with respect to openness, developer friendliness, attitude toward open source, product quality, etc. It seems clear to me that there is some broad cultural change at MS and it seems plausible that it could affect documentation quality as well.

Personally, I don't have a dog in this documentation fight, but your comment seems unjustifiably angry.

Re: The Elephant at WWDC

#97

Post by afavour »

This speaks to me. I’m not deeply involved in the iOS development world but I do a lot of webview-adjacent stuff so I keep a close eye on the WKWebView documentation.

It’s a mess. Case in point: introduced in the new beta: loadSimulatedRequest:

https://developer.apple.com/documentation/webkit/wkwebview/3...

What does it do? Don’t know. I can make a few informed guesses from the name but I’m not sure if it’s maybe a performance measurement tool, or just a way of loading faked data. There is no documentation. To the best of my knowledge it isn’t covered in any talks either.

Re: The Elephant at WWDC

#98

Post by moralestapia »

the-dude wrote: post #94
moralestapia wrote: post #69

Something I really loathe about OS X, and it has been becoming worse with time, is the amount of "processes" or whatever that suddenly take 100% CPU. There's no place to find out what they are. What are they doing, are they from apple or not? You're hopeless, aside from some comments here and there from random members of the community. To this day, I have no idea what 'powerd' is, for instance.

And you couldn't be bothered to do a cursory search? > There's no place to find out what they are. Google worked fine for me. YMMV.

Could you please, then, point me to a creditable source regarding what 'powerd' is?

Re: The Elephant at WWDC

#99

Post by p_l »

defaultname wrote: post #84
nextweek2 wrote: post #76

Earlier quoted context omitted.

> Microsoft has had superb documentation for decades No, they've had lot's of documentation. That's not the same thing. For decades it was very shallow with no examples. You'd get an enum list with a half sentence explanation. The last couple of years they've really upped their game. With detailed examples, explanations and even source in multiple languages. To me Qt's documentation was the benchmark, but the latest…

"No, they've had lot's of documentation. That's not the same thing. " This kind of snotty reply is always interesting. I've been a professional developer for 25 years. For most of those years I was deep in the Microsoft platform. C++, Win32 API, DirectX, COM+/DCOM, OLE, automation, C# / .NET. For decades they've had exhaustive narrative documentation that would give huge backgrounders on everything. Architectural "ho…

arguably it's been the last decade that documentation from MS suffered, specifically around the time that their software stopped shipping with CHM&co files and started opening web pages.

But they are quite actively rebuilding from the switchover. I still miss CHM.

Re: The Elephant at WWDC

#100

Post by GordonS »

justinclift wrote: post #91
bob1029 wrote: post #30

Conversely, I have noticed that Microsoft has been kicking some serious ass in the documentation arena lately. If you haven't taken a look at their stuff in a while, you would probably be shocked. Here's a high level overview of GC to give you an idea of how thorough these documents are now: https://docs.microsoft.com/en-us/dotnet/standard/garbage-col... After reading through all of those sections, I will have develo…

Conversely, when looking through the Azure documentation last week for much of their Python SDK libraries... it's a joke. They have _tonnes_ of new-user intro stuff and similar. Super impressive at first look, but once you're past that and need to dig into complicated things it's all undocumented. Even most of the auto-generated pages in their Python SDK function lists are just "Header -> empty space where content sh…

I'm a heavy user of Azure, and I have 2 general issues with their docs.

Firstly the documentation for the various SDK is often an issue, because it's often behind the latest release of the SDK.

For .NET libraries especially, there is just so much churn that they obviously struggle to keep the docs updated.

And then secondly, as you say, there just aren't enough examples beyond the most trivial.

Post reply on HN