On Apple's Piss-Poor Documentation • Hacker News Board

Re: On Apple's Piss-Poor Documentation

#101

Post by Humdeee » Tue, Nov 10, 2020, 5:35 PM UTC

wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

I believe someone like Paul Hudson and the work he has done can influence a language's adoption by nearly an order of magnitude in the language's infant stages.

I released a Swift 1.0 app back in 2015, and continue to provide irregular updates for it but still churns some decent income (to me). If not for him, I really don't think that spark of enjoyment would have happened. What he provided was two-fold: an enthusiast to Swift and the iOS environment, and also as a teacher and big source of documentation.

Re: On Apple's Piss-Poor Documentation

#102

Post by justin_oaks » Tue, Nov 10, 2020, 5:36 PM UTC

I wonder if there is a way to get Apple's attention. There's a lot of power in collective action. It'd be interesting to see what would happen if every developer who was unhappy with the documentation put in an email, a call, or a support ticket.

Re: On Apple's Piss-Poor Documentation

#103

Post by Zelphyr » Tue, Nov 10, 2020, 5:36 PM UTC

Marco is right about PHP's documentation. I've felt for a long time that the quality documentation PHP provided played a major role in the language's success.

Re: On Apple's Piss-Poor Documentation

#104

Post by GnarfGnarf » Tue, Nov 10, 2020, 5:36 PM UTC

StillBored wrote: post #77

chromanoid wrote: post #67

Earlier quoted context omitted.

Did you ever look at the Windows API documentation?

Yes, and I know the complaints. Lets look at https://docs.microsoft.com/en-us/windows/win32/api/synchapi/... Function description, supported version information, header-file and library file information, meaningful return code documentation, links to an overview of the system wait behaviors, documentation about what happens in low power situations, links to example code using the function, differences in behavior bet…

Charles Petzold is immortal!

Re: On Apple's Piss-Poor Documentation

#105

Post by ericlewis » Tue, Nov 10, 2020, 5:37 PM UTC

jimmoores wrote: post #83

The only thing that might make Apple improve their documentation is if there was evidence that people started actually abandoning Apple's platforms. Currently it seems there is a never ending supply of developers ready to gamble years of their careers on Apples Terms & Conditions, and while these same people usually eventually realize that there's ultimately no money to be made, they are replaced with a new generatio…

There is a lot of money to be made working on iOS for big corp. hell, even small startups.

You seem to allude to indie devs though, so I can agree that it would be insane to attempt to go out on your own without essentially being a startup in your own right.

Re: On Apple's Piss-Poor Documentation

#106

Post by justinclift » Tue, Nov 10, 2020, 5:40 PM UTC

egsmi wrote: post #62

pornel wrote: post #53

Earlier quoted context omitted.

Yes! Apple used to have Technical Notes that were a deep dive into how the OS is implemented. They were super helpful in troubleshooting and optimizing for Mac OS. They haven't published anything like this in over a decade. I suspect someone took "hiding implementation details" too seriously, and now Apple never talks about how anything works (it's all magic). You only get function's signature, and "documentation" th…

There are good reasons to hide the implementation details in documentation. The primary being it’s easier to keep the documentation up to date, our primary topic here. Many languages even publish class interfaces but not necessarily implementation details. That said, a couple of example code snippets on using the interface wouldn’t hurt.

> The primary being it’s easier to keep the documentation up to date ...

That's NOT a "good" reason in any sense.

That's a terrible reason, which no-one in a team leader or above position should ever sign off on.

Re: On Apple's Piss-Poor Documentation

#107

Post by Ronsenshi » Tue, Nov 10, 2020, 5:40 PM UTC

ProAm wrote: post #82

wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

> So instead you end up on 3rd party tutorials...How do you know if the feature changed significantly in the more recent release? I don’t know, but I can tell you where you won’t find out: the official docs. Get ready for documentation subscriptions. I wish I were joking.

Already a thing:

https://apps.apple.com/us/app/a-companion-for-swiftui/id1485...

No affiliation. It's sad and a bit pathetic that trillion dollar company can't hire even one person to work on public documentation.

Re: On Apple's Piss-Poor Documentation

#108

Post by auggierose » Tue, Nov 10, 2020, 5:42 PM UTC

orangefarm wrote: post #91

I can't get my head around why their documentation is so poor. They should have all the resources in the world to recruit people that have proven to write good documentation. If open-source projects run by volunteers can have excellent documentation (e.g. Vue), why can't Apple? Better docs mean a better developer experience which means more people want to (and are able to) develop apps for iOS which increases the val…

I think what is happening here is that the attitude of Apple towards normal users is spilling over to its attitude towards developers. Which is obviously a big problem, if that is indeed the case.

Re: On Apple's Piss-Poor Documentation

#109

Post by grp000 » Tue, Nov 10, 2020, 5:45 PM UTC

mrtksn wrote: post #99

ProAm wrote: post #82

Earlier quoted context omitted.

> So instead you end up on 3rd party tutorials...How do you know if the feature changed significantly in the more recent release? I don’t know, but I can tell you where you won’t find out: the official docs. Get ready for documentation subscriptions. I wish I were joking.

That actually sounds good. When you pay for something it implies that you might stop paying for the thing if you’re not happy which means the seller is likely to work hard to make you happy. I would love to have paid version of most of the apps/sites I use. Not ad-free subscription but paid version where I can be the unhappy customer when I am unhappy.

That would make sense if documentation were a standalone product, but it's completely complementary to the language, so that doesn't make any sense.

Re: On Apple's Piss-Poor Documentation

#110

Post by GnarfGnarf » Tue, Nov 10, 2020, 5:46 PM UTC

Have you considered using Qt? It compiles and runs native on macOS, the documentation is superb. You just let the Qt people worry about the Cocoa, Quartz etc. interface.

As a bonus, it will also run on Windows, Linux, Android, iOS.

Qt looks like an "operating system". It isn't really an O/S, it feeds off the underlying O/S, but to the applications programmer, it completely subsumes the O/S.

We converted a 500KLOC Win32 app to Qt (and macOS), and there is not one single Win32 API call left, except for an obscure font enumeration thing because we wanted to stay with our own PDF code instead of using Qt's.