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

On Apple's Piss-Poor Documentation

caseyliss.com

Post reply on HN
Print view View original

231–240 of 348 posts

Re: On Apple's Piss-Poor Documentation

#231

Post by GnarfGnarf »

jes5199 wrote: post #172
GnarfGnarf wrote: post #110

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 Win…

I can always tell when I'm using a Qt app on my mac, because my keyboard navigation shortcuts don't work

Thanks for mentioning that, I'll try and make sure we accommodate keyboard navigation shortcuts.

Re: On Apple's Piss-Poor Documentation

#232

Post by wlesieutre »

ethbr0 wrote: post #204
wlesieutre wrote: post #192

Earlier quoted context omitted.

There's an old saying at Microsoft: developers, developers, developers, developers, developers, developers, developers, developers

It's mocked, but the underlying observation is astute. In the personal computing world, first parties can't build enough user software. Furthermore, software availability and reliability lag third party developer and development ecosystem health. A bad experience doesn't hurt the platform today , it hurts the platform in 1+ years. And perhaps even worse, steps to address it take effect over a 1+ year timeframe as wel…

Mocked at the time, but looking back it sounds pretty good. Maybe Apple needs a Steve Ballmer.

Re: On Apple's Piss-Poor Documentation

#233

Post by [deleted] »

dragonwriter wrote: post #143
qayxc wrote: post #136

Earlier quoted context omitted.

That's a bogus claim! The MSDN documentation has always been freely available. The subscription service included all of Microsoft's software editions for development purposes and that's what subscribers actually paid for. The documentation of software packages, APIs, and driver kits was freely available online.

> The MSDN documentation has always been freely available No, it hasn't. It was originally available exclusively to subscribers, and only on CD. MSDN started before the web existed. Eventually , the documentation became free on the web.

[deleted]

Re: On Apple's Piss-Poor Documentation

#234

Post by lostcolony »

grimjack00 wrote: post #120
lostcolony wrote: post #86

Earlier quoted context omitted.

I've run into this more often than I can count with Java based things. "Just look at the Javadocs!" You...you mean the auto-generated API descriptors that have exactly zero usage information on them, and expect me to figure out how to piece things together just by type signature? That...that isn't how documentation works.

You mean you can't figure things out from "public Session getSession(String, String, String, String, String)"?

That I could probably look at the source and figure things out.

No, what kills me is

public Session getSession(Foo, Bar, Baz)

where Foo, Bar, and Baz are themselves interfaces, and I have no idea what implementing class I need, so I go searching, and after an hour of pain piece together that I need to instantiate a NotAtAllAFooButNeverthelessImplementsFoo, then pass that into the BuildingFactory class' static factory method to get an instance of Bar, and then I can just pass in a null for Baz, and it -seems- to work.

Re: On Apple's Piss-Poor Documentation

#235

Post by qayxc »

dragonwriter wrote: post #143
qayxc wrote: post #136

Earlier quoted context omitted.

That's a bogus claim! The MSDN documentation has always been freely available. The subscription service included all of Microsoft's software editions for development purposes and that's what subscribers actually paid for. The documentation of software packages, APIs, and driver kits was freely available online.

> The MSDN documentation has always been freely available No, it hasn't. It was originally available exclusively to subscribers, and only on CD. MSDN started before the web existed. Eventually , the documentation became free on the web.

> It was originally available exclusively to subscribers

No it wasn't - the subscription service shipped CDs (and later DVDs) with technical articles, updated SDKs and the like. The actual documentation was always included with every Visual Studio version on the installation discs.

I remember quite vividly the "joy" of re-installing the latest version because the documentation format was incompatible between releases and you could either reinstall the new version from disc (which took ages) or convert the already installed one (which also took ages, but not quite as long as juggling 4 CDs - it had to "rebuild the index" or some nonsense like that IIRC).

So if you owned a physical copy of any Visual Studio edition, you also had the documentation and thus no need to subscribe to MSDN (apart from the technical columns, SDK updates and the magazine, which any reasonable boss would allow you to read during work hours).

Re: On Apple's Piss-Poor Documentation

#236

Post by ChrisMarshallNY »

bsenftner wrote: post #183
ChrisMarshallNY wrote: post #23

Earlier quoted context omitted.

I once owned every copy, of every generation of "Inside Macintosh." I agree about the Android docs. However, in defense of companies that don't like to have too much documentation around, I can tell you, from personal experience, that writing developer docs is hard , as is doing developer support. Keeping them up to date is also a challenge. I call it "concrete galoshes": https://littlegreenviper.com/miscellany/concr…

I was a Mac beta tester back in '83, and still have a copy of the pre-release "Inside Macintosh" mimeographed the day after the original programmers wrote their drafts, filled with penciled in corrections and in some places pages of hand corrected notes. Reviewing a formal copy after edition 2 or 3, I was surprised to see a reduction in information quality and some of the key information from the penciled in notes co…

That is a cool story.

I got my first Mac in '86 (a Mac Plus).

My first copy of Inside Macintosh was the hardcover. I think it was two volumes, back then.

Re: On Apple's Piss-Poor Documentation

#237

Post by thombles »

_qulr wrote: post #64
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…

The other day someone referenced this post by an Apple engineer: https://developer.apple.com/forums/thread/663858 Why in the world is this a random undiscoverable post in the (terribly designed) developer discussion forums rather than a Technical Note in the documentation? It would have been a TN in the past. In fact that same engineer wrote a number of old Apple TNs. It's clear even to some within Apple that there's…

I would struggle to get many things done if not for that one particular Apple engineer and their forum posts.

Re: On Apple's Piss-Poor Documentation

#238

Post by alexashka »

auggierose wrote: post #191
alexashka wrote: post #148

Earlier quoted context omitted.

SwiftUI is not great in any sense, other than looking great to people who've never written non-trivial software. When your criteria for 'great' is whatever 'content creators', 'software journalists' (email newsletter 'creators') and apple's marketing team pump out this week, 'great' is anything a marketing firm puts dollars behind that seems 'cool' and 'fresh' and 'hip', or is it 'dope' this week? It is quintessentia…

I've actively made an effort to learn SwiftUI this week so I can write my software quicker. I don't want to spend hours on displaying some styled list in my apps, that should be done in a few minutes. SwiftUI allows for that. Once all the bugs are gone, that is. So far, I've spent a lot of time on SwiftUI's bugs. Luckily, you can always dive down to UIKit if all else fails. SwiftUI brings concepts from React and Flut…

Ah, we are so lucky to have a framework full of language features that only it uses and an ability to drop down and learn a whole other suite of frameworks that work completely differently to achieve the same task!

I've been so lucky to have to learn near a dozen programming languages in the span of less than a decade to write CRUD apps that appear on screens and do the same thing on each platform slightly differently.

I only hope to be more lucky in the decades to come, maybe I'll have to learn two dozen new languages and three dozen new frameworks to write CRUD apps that show up on computer screens.

Re: On Apple's Piss-Poor Documentation

#239

Post by corty »

samatman wrote: post #207
corty wrote: post #145

Earlier quoted context omitted.

Apple developers are a captive audience, they will pay their annual hundred bucks and develop for iShiny no matter how crappy the docs are. There are just too many rich users and clueless PHBs demanding apple development to miss out. If those reasons went missing and Apple really had to compete for developer mindshare, docs would improve. Which leads to the solution: Quote a lot more for Apple development or don't de…

This answer doesn't really work for me. iOS is Apple's bread and butter, and they make good money off those developers. It's in their cynical self-interest to spend the money to have the best documentation in the game, and it would even pay off inside Apple, with better APIs and better resources for their in-house teams to develop against. It seems like a genuine institutional dysfunction. Apple has a culture of secr…

I can also do handwaving culture arguments like apple design in a minimalist fashion, so everything that can be left out will be, including documentation. But I don't like those, I hate to diagnose cultures I only read about.

However, apple is a business, and leaving out docs makes business sense and is an easy and straightforward explanation.

Re: On Apple's Piss-Poor Documentation

#240

Post by auggierose »

alexashka wrote: post #238
auggierose wrote: post #191

Earlier quoted context omitted.

I've actively made an effort to learn SwiftUI this week so I can write my software quicker. I don't want to spend hours on displaying some styled list in my apps, that should be done in a few minutes. SwiftUI allows for that. Once all the bugs are gone, that is. So far, I've spent a lot of time on SwiftUI's bugs. Luckily, you can always dive down to UIKit if all else fails. SwiftUI brings concepts from React and Flut…

Ah, we are so lucky to have a framework full of language features that only it uses and an ability to drop down and learn a whole other suite of frameworks that work completely differently to achieve the same task! I've been so lucky to have to learn near a dozen programming languages in the span of less than a decade to write CRUD apps that appear on screens and do the same thing on each platform slightly differentl…

Well, stop writing CRUD apps! That's boring indeed. How about you do some real software?
Post reply on HN