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

141–150 of 213 posts

Re: The Elephant at WWDC

#141

Post by taftster »

gambiting wrote: post #71
defaultname wrote: post #44

Earlier quoted context omitted.

Microsoft has had superb documentation for decades. They put a lot of emphasis on it and the results show. The linked article is a bit off base, I think, because clearly Apple's documentation problem isn't a tool issue. It's a philosophy of documentation. I like going to the documentation for a critical system API class and finding all of the members, examples for each, and then "related" things. Philosophically Appl…

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…

Right. And this would be so easy to fix too.

  a) crawl your own documentation and find dead links.
  b) monitor 404 errors and track down the source (via referer headers, etc.).
  c) ask the user on the 404 page what they were hoping for or provide a search menu, record it, and have someone manually review.
  d) add a redirect management engine, so you can redirect links that you can't/won't ever fix.

Re: The Elephant at WWDC

#142

Post by worik »

wvenable wrote: post #106
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…

I agree with both of you -- Microsoft documentation is generally excellent and extremely detailed and often more than just what you'd get from automatically generating it from code comments. But the tools constantly send you to links that don't work or provide no useful information. It's a very weird disconnect. I never trust the "click here to open documentation page".

Half right....

Re: The Elephant at WWDC

#143

Post by worik »

I learnt to programme on a Mac Plus using Pascal (Lightspeed? I cannot remember the brand). Inside Macintosh is still, after thirty years, in a box some place. I will never throw it out. Well thumbed, and very useful.

Been nearly a year back with Apple hardware now. What a change! The tools are very flash, but nothing quite works. The easy bits are done, feels like 95% of perfect. The documentation is good if you just need to be reminded, but if you need anything to help in the early part of the learning curve, it is third party blogs, (that really feel to me like astro turf, but they do exist).

The licensing! Why do I keep getting blocked from using hardware bought and paid for! My colleagues and I have spent, literally, days trying to get me into some sort of licensing scheme - truly Kafkaesque.

It feels a lot like Linux in 1997 - mostly works and brimming with potential. But whilst Linux was on its way up in 1997, Apple feels like it is on its way down.

And they are busy fighting to keep quasi legal monopolies instead of fixing the last few problems in their tools and writing proper documentation. What a shame

Re: The Elephant at WWDC

#144

Post by 3grdlurker »

It’s odd that no one has pointed out yet that the article is conflating macOS user documentation with developer documentation.

In the first place, and this is an unpopular opinion, people have simply accepted “Apple's documentation sucks” as truth but the documentation problem hasn’t been properly defined or framed yet. I personally think that the view, view controller, Core Data, animation, networking, and Bluetooth, and concurrency guides are excellent. What parts of the Apple SDKs exactly are people having a problem with? If it’s just the latest APIs like SwiftUI, does that make the whole platform deserving of an unqualified negative perception? I don’t think so, and it doesn’t help that in my experience, the people who complain the most about Apple’s documentation are the ones who go to a Medium article first and before consulting Apple’s own documentation.

Re: The Elephant at WWDC

#145

Post by cxr »

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…

> The best thing for me is that when I click the "Edit" button on Microsoft's documentation, it takes me directly to the latest markdown source file on GitHub and I can immediately submit a PR

We had better than that 10+ years ago: actual wikis. We've regressed quite a bit. Even developer.mozilla.org has gone backwards. Had devmo not been a wiki, I'd have never poured so much effort into the JavaScript docs between 2006–2008.

Re: The Elephant at WWDC

#146

Post by andrekandre »

my interpretation of this situation is, if (whether by intention or not) it can be outsourced, it will be outsourced

---

there are lots of third-party sites that do a great competition with apple for documentation, especially for swift/swiftui and i get the feeling that apple is maybe conflicted... they want to solve thier problem of documentationm but

1. there are lots of great (albiet scattered) resources on the internet already

2. things change radically year after year (uikit → swiftui, x64 → arm, etc); its hard to maintain a "tome" at apples pace and scale

3. apple is all about effeciency; stopping to write a book when you could be coding or innovating doesnt seem worth it

.... its a difficult situation and would probably cost a lot of money and resources, and logistically, seems like it would slow up development quite a bit (even if someone else wrote the books, you still have to coordinate with the devs)...

Re: The Elephant at WWDC

#148

Post by zeusk »

taftster wrote: post #141
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…

Right. And this would be so easy to fix too. a) crawl your own documentation and find dead links. b) monitor 404 errors and track down the source (via referer headers, etc.). c) ask the user on the 404 page what they were hoping for or provide a search menu, record it, and have someone manually review. d) add a redirect management engine, so you can redirect links that you can't/won't ever fix.

I'll write a crawler and get this done for CGA docs (Compute, Graphics and AI).

Thanks for the tip.

Re: The Elephant at WWDC

#149

Post by fortran77 »

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…

Apple documentation has been awful for decades. There’s so much history and insider knowledge you need to write good desktop MacOS applications.

And Microsoft documentation has been excellent for decades. Even pre-Internet with MSJ and Microsoft press.

Re: The Elephant at WWDC

#150

Post by fortran77 »

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

It’s a typical HN Apple Zealot tactic. They simply lie to boost their cult.

Post reply on HN