Live data from Hacker News

On Apple's Piss-Poor Documentation

caseyliss.com

221–230 of 348 posts

Re: On Apple's Piss-Poor Documentation

#221

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.

100% agree.

Every method and object needs five things: 1) what parameters does it need to be used or created 2) what values does it return if any 3) a simple description of what it does 4) a simple canonical example of it being used that can be copy/pasted as a template 5) notes from devs which can help elaborate on the above.

This is pretty basic, but where PHP nails this, so much other documentation completely ignores one or more parts. Finding a return value in Python docs usually means reading through a paragraph of text or using dir() from a command line. Figuring out how to use a Javascript Object can often mean jumping around MDN looking for a reference, unless the feature is super new, then all you might get is a signature. Android documentation will give you everything but examples.

Objects and functions are like parts of an engine. You need to know what each piece is used for, where it goes, how to install it and the way it all fits together.

Re: On Apple's Piss-Poor Documentation

#222
post #59

Earlier quoted context omitted.

> The poor documentation defends expert third party developers against competition from new entrants. It ensures a shortage of competent developers and so enhances the revenue of established experts. Why in the world would Apple want to ensure a shortage of competent developers — for apps on Apple's platforms! — or protect third party experts?

Apple slowly wants to pump out their own apps that do everything to maximize their recurring subscription revenue. Why settle for 30% when you can take 100%.

There is no evidence of them doing that. Pretty much the contrary is happening.

Re: On Apple's Piss-Poor Documentation

#223
post #62
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.

Following that reason, the easiest way to keep the documentation up to date is to not have documentation.

Re: On Apple's Piss-Poor Documentation

#224

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…

The author is a podcaster and developer pretty much focused on Apple and mostly iOS. I think developing for other platforms is a total non issue for him and he also hates C++. I doubt Qt would be an option.

Re: On Apple's Piss-Poor Documentation

#225
post #62

Earlier quoted context omitted.

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.

Following that reason, the easiest way to keep the documentation up to date is to not have documentation.

It’s always the null cases that get you... I suppose if “up to date” was the only requirement I would agree. But in reality there are many competing requirements which is why there are many degrees of documentation. Obviously internal and external documentation will be different too.

Re: On Apple's Piss-Poor Documentation

#226

Earlier quoted context omitted.

I will say that the WWDC sessions are well presented, and are a good place to start. But you can't use a video for quick reference, and you might be missing context from knowing how it worked the previous year to understand what the new enhancements are. Expect to dig into 2019 videos too. SwiftUI being new at least has the benefit that its sessions can't be any more outdated than that (yet). At most you're reconcili…

I don't really consider most WWDC videos documentation. They're usually just marketing videos which show off the new features. Even the more in depth videos are rarely more than a shallow introduction.

Unfortunately there's bits of information that are important and only ever appear in the WWDC videos.

Re: On Apple's Piss-Poor Documentation

#227

Earlier quoted context omitted.

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.

It’s because engineers don’t want to write documentation, and if you don’t force it this is the result.

You have to give them time to write it, too.

Re: On Apple's Piss-Poor Documentation

#228
post #204

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…

Apple used to be better about developers, I think, back 2000-2010 or so.

Re: On Apple's Piss-Poor Documentation

#229
post #158

Earlier quoted context omitted.

Just hire Microsoft's people. Not even joking. https://docs.microsoft.com/en-us/dotnet/api/system.string.su...

For all the crap that Apple, Java and other open-source people have piled on Microsoft over the years, their developer documentation has always been very good. Yes, there are rough-edges. Back in the day, when Sun was still in-charge of Java, I had my 1-person consulting company partner with Sun and become an official "Certified Java" organization... Great, I thought - now I can get some better documentation... Sure,…

I wouldn't say it's always been very good. How well do you remember MSDN? In the mid-2000s, Microsoft documentation lived on three or four separate sites, and I don't remember the names of all of them. The two that spring immediately to mind are MSDN and TechNet. MSDN had the infuriating issue of broken links. You'd be deep-diving on an issue, find a link to an article that looked like it might perfectly address your question, and... 404.

It got so bad that a VP ended up making a pronouncement, declaring a war on broken links. He announced a multi-year plan to reduce and eventually fix all the broken links on MSDN. This was the vacuum that was partially responsible for the birth of Stack Overflow.

Re: On Apple's Piss-Poor Documentation

#230
post #82

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.

>Get ready for documentation subscriptions. I wish I were joking

I thought that was what the $99/year was for.

Post reply on HN