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

71–80 of 348 posts

Re: On Apple's Piss-Poor Documentation

#71

Post by coldcode »

pornel wrote: post #53
psahgal wrote: post #7

Has anyone else noticed that Apple has been slowly moving away from the long-form guides that were helpful at explaining core concepts? I remember once seeing a comprehensive guide on code signing, but over the years it appears to have been scrubbed from their documentation resources. In its place is a much less helpful (but prettier-looking) guide. In comparison, I've noticed Android has FANTASTIC developer document…

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…

When I worked at Apple in the mid 90's, DTS had to hire someone to go around to every engineering team to collect what they had change so we could write a tech overview of an OS release, otherwise no one would have known what changed. But then was when Apple was going out of business.

Re: On Apple's Piss-Poor Documentation

#73

Post by tonyedgecombe »

forty wrote: post #37

Why would they improve the documentation? It's not like you have a choice anyway, you will have to figure out, since you cannot ask your customers to switch to another mobile platform... They really don't give a shit about developers. I'm a backend developer, their In App Purchase system is the worse API I have been unfortunate to work with (and it's much better than what it used to be)

I had a choice, I decided not to develop any software for the Mac.

Re: On Apple's Piss-Poor Documentation

#74

Post by analog31 »

toopok4k3 wrote: post #49

I don't think Steve would have allowed this to happen. Developers are way too important part of the whole "where the money comes from?" question. He would have noticed the complaints before anyone wrote a blog about it. iOS docs were great back in 2011.

Docs for the 68k Mac were abysmal. There was a collection of books entitled "Inside Macintosh" that were nearly impenetrable, and only scratched the surface of the elaborate class libraries. Instructions for creating "Hello World" on the Mac were dozens of pages long.

From what I've read, Jobs certainly understood the importance of software, but only great software. He didn't want the Apple ecosystem to become loaded up with crapware like on the IBM, or on the Apple ][ for that matter. So, if a small time developer couldn't write and distribute a crude but useful app, so be it. Favored developers probably didn't fare any better with the documentation, but help was a phone call away.

This was the "closed box" philosophy that I don't think has changed much over the years.

The irony was that "crappy but open" attracted more developers than "wonderful but closed." This is why apps such as assemblers for microcontrollers were written for MS-DOS. Essentially, even after the introduction of MS Windows, the ability to write for DOS provided a way to create and share simple apps.

Re: On Apple's Piss-Poor Documentation

#75

Post by [deleted] »

ChrisMarshallNY wrote: post #23
psahgal wrote: post #7

Has anyone else noticed that Apple has been slowly moving away from the long-form guides that were helpful at explaining core concepts? I remember once seeing a comprehensive guide on code signing, but over the years it appears to have been scrubbed from their documentation resources. In its place is a much less helpful (but prettier-looking) guide. In comparison, I've noticed Android has FANTASTIC developer document…

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…

[deleted]

Re: On Apple's Piss-Poor Documentation

#76

Post by gumby »

It's really a shame that a scrappy little company like Apple can't afford the resources to produce documentation, even if not for their own apps at least for the developers who write apps that cause their users to buy the hardware. Maybe when they can get themselves established in the market they'll have enough financial resources to invest in this critical area.

===

I never liked Ballmer, and really never liked the win APIs, but I fell in (technical) love with him after the much derided "developers developers" dance he did. In that regard he clearly understood who buttered his bread.

OTOH Apple treats WWDC as the entirety of their developer outreach, when really it should merely be the cherry on top.

Re: On Apple's Piss-Poor Documentation

#77

Post by StillBored »

chromanoid wrote: post #67
StillBored wrote: post #50

This isn't an apple thing. Its industry wide. Much of the good documentation that exists is stuff that was written 20+ years ago by actual technical writers and is still being maintained. AKA the windows API/etc documentation, linux man pages, etc. The vast majority of modern documentation is worthless autogenerated garbage when it exists. It lacks good examples, meaningful overviews and functional diagrams. In many…

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 between differing versions, it goes on and on.

Can you point to something you think is better?

PS: I should point out, I have paper copies of the win32 api from the early 1990's that are falling apart from the use they got.

Re: On Apple's Piss-Poor Documentation

#78

Post by creativityEng »

musha68k wrote: post #29

I feel as if Apple has let down the software industry by “going with the times” in general. A “north star” to lots of designers and engineers from interaction design all the way down to the systems level. Excellent documentation was part of it. Long game. Best practices. The whole “crafting” DNA seems to have been lost somewhere along the journey. I think it’s also a function of market driven angst and hence not sayi…

There's a huge disconnect between informed consumers and the average Apple product owner.

I read an ancedote from an aspiring SWE that after he saw the Apple product he couldn't afford, he knew he needed it.

People aren't buying because quality reasons, they buy because of various psychology tricks their marketing department is responsible for.

It creates a system where developers are dragged along to support 100% of users.

Re: On Apple's Piss-Poor Documentation

#79

Post by dreamcompiler »

Apple no longer gives a shit about developers because they don't have to. They ship as many IOS devices as the China factories can produce and dump trucks full of money keep lining up outside the front door. Why should they spend money on technical documentation, or better developer tools, or even the quality of their desktop operating systems? Those things don't make Apple money.

What makes Apple money is building pretty, locked-down computerlike appliances that are completely under Apple's control. I don't think Apple even sees developers as necessary any more, except the ones in their employ.

Re: On Apple's Piss-Poor Documentation

#80

Post by seemack »

toxik wrote: post #15

Honestly, reading the headers is the only way to understand iOS, macOS, and iPadOS properly. I find that the older I get, the more _code is my documentation._ Particularly for things like Python's matplotlib, once you do more than put lines or scatter plots together, you _have_ to understand how the code actually works. Of course, that's difficult when all you get is header files, but still...

I get the mindset and am very much a read-the-code person as well but my go-to example for this kind of thinking is that reading the code in lieu of a written summary/guide, etc is like trying to understand a book where the chapters and paragraphs are mixed around. It's possible and the ability to do so worthy of pride but it's clear that a succinct summary in one place would be far easier and time-efficient.

Not to say that heavy documentation like this is perfect of course. It just seems like the complexity of the read-the-code solution is sometimes glossed over.

Post reply on HN