6 ms·
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
by pornel 6y ago
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" that is basically just the function name with added spaces between words.
- egsmi 6y agoThere 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.
- justinclift 6y ago> 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.
- egsmi 6y agoWe're going to have to agree to disagree on this one. But let me give you all an example. Wolfram Documentation on Mathematica is excellent in my humble opinion. Here is a function I use very often, convolve. https://reference.wolfram.com/language/ref/Convolve.html https://reference.wolfram.com/language/ref/Convolve.html Notice how the interface is very well described, there are examples on how to use it, but there are no implementation details.
- justinclift 6y agoYour reference example includes lots of details, examples of usage including source, explanation of options, etc. :) That's not an "easier to keep documentation up to date" type of thing ;), but is definitely an example of good documentation. Unlike the Apple approach mentioned above. :( :( :(
- ironmagma 6y agoFollowing that reason, the easiest way to keep the documentation up to date is to not have documentation.
- egsmi 6y agoIt’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.
- jonhendry18 6y agoThe reason to keep implementation details out of the docs is that people will rely on those implementation details, and then when their app breaks, they won't even think of looking at the documentation for updated implementation details. After all they probably have the old version all but memorized, and the app may break in a way that isn't obviously related to the implementation that changed.
- _qulr 6y agoThe other day someone referenced this post by an Apple engineer: https://developer.apple.com/forums/thread/663858 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 a need for more and better documentation, but some pointy haired boss in upper management seems to think the current situation is fine.
- hutzlibu 6y agoCurrent situation is, money is coming in. Stock market still loves apple. So for them it seems fine.
- Polylactic_acid 6y agoBasically. What are you going to do? Not release your app on apple devices? No, you will do whatever it takes to work it out yourself.
- lmm 6y agoIt might even be in their interests to drive away all but the most dedicated developers. After all, they have more apps than they'll ever need, the problem is always quality.
- _qulr 6y ago> the problem is always quality But writing quality apps requires quality API documentation. I don't know how developers fumbling around in the dark can result in quality apps. Being "dedicated" to Apple platforms is not the same as being dedicated to quality.
- thombles 6y agoI would struggle to get many things done if not for that one particular Apple engineer and their forum posts.
- coldcode 6y agoWhen 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.