7 ms·
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
by psahgal 6y ago
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 documentation. I've found full guides for everything. Even esoteric classes that are rarely used have at least a little bit of documentation.
- layoutIfNeeded 6y agoThis. Their documentation on CoreAnimation concepts was wonderful [1]. It even has these little appendix sections discussing advanced use-cases. Sadly, they seem to have stopped writing these at around 2015... [1] https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/CoreAnimation_guide/Introduction/Introduction.html#//apple_ref/doc/uid/TP40004514 https://developer.apple.com/library/archive/documentation/Co...
- saagarjha 6y agoRelevant username?
- tmpz22 6y agoMy guess is they’re realized documentation is a huge cost center and even their own technical writers are overburdened by the churn of deprecating APIs and changing best practices. It’s worse then the JavaScript community.
- psahgal 6y agoI find this business decision fascinating because a good portion of their App Store revenue comes from developers. One would THINK developer relations would be a priority at Apple, but it's pretty clear that's not the case. It was one of things that I found unbelievable when switching from Android to iOS development. The developer experience is just so much WORSE on iOS. Sometimes, it's as if Apple is actively trying to annoy developers.
- chungus_khan 6y agoThey have such a strong market presence and so much power, they don't have to care for the moment because developers will come to the platform anyway.
- jonhendry18 6y ago"documentation is a huge cost center" It's a tiny cost center, in the grand scheme of things. As it is they probably spend less than they spend cleaning the glass at Apple Park.
- dragonwriter 6y agoFor API documentation, if you can specify what you intend to build well enough to build it and validate that you have built even approximately what you intended to build, documentation shouldn't be much more work.
- mtc010170 6y agoI'm curious who maintains the Android docs. Is it all open source? Is any of Apples?
- psahgal 6y agoBased on the Android source code I've seen while working on Android projects, I think a good portion of the Android docs are generated by the inline documentation from the Android open-source project. But on top of that, Google also produces high-quality long-form guides. Those are first-party guides, found at https://developer.android.com/ https://developer.android.com/. (Google maintains the Android developer site.)
- mtc010170 6y agoAh ok, thanks for the response! I've seen a lot of value in automatically generated docs from inline code. Perhaps that's a key baseline strategy for improvement. Add then padding that with the long-form guides with concepts and examples.
- danpalmer 6y agoThe long form guides are great, but for much of SwiftUI they're even missing the most basic 3-line summary of what a thing is. I so often need to do a simple thing, find a function that looks about right, and the documentation for it says literally nothing about how to use it.
- ChrisMarshallNY 6y agoI 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/concrete-galoshes/ https://littlegreenviper.com/miscellany/concrete-galoshes/
- deleted 6y ago[deleted]
- bsenftner 6y agoI 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 completely missing.
- ChrisMarshallNY 6y agoThat 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.
- bsenftner 6y agoThe original Inside Mac was 3 volumes, after their initial printing of the "phone book edition" - all three volumes in one thick soft spine binder. I really need to take the time to scan my copy and put it online. It's got ballpoint pen corrections from the Apple Engineers telling the beta testers various fixes.
- Fradow 6y agoAndroid HAD fantastic documentation, just like Apple had 7/10 years ago. It might not be overly apparent just yet to everyone, but Android documentation is slowly following the same path as Apple documentation, where the experience is slowly degrading, but since it was so good a few years ago, that degradation didn't creep everywhere just yet. My coworker and me are already starting to feel the pain on various core APIs, the latest being notifications, which according to my coworker had 3 full revision, and finding documentation for the last one is hard. Storage (with Android 11 modifications) is another place where the documentation is starting to get stale. Those are not the only APIs were the documentation was poor. In my opinion, Android documentation is at the same place iOS documentation was about 5 years ago (before they started removing entire pages from the documentation) : overall very good, but a few places were it's not up-to-par or downright horrible. I don't expect the quality to improve in the future.
- psahgal 6y agoEven 5 years ago, I felt that Apple's documentation was way worse than Android's. I wonder if there is a good way to measure documentation quality...I suspect such measures will require techniques borrowed from user experience research.
- hutzlibu 6y ago"I wonder if there is a good way to measure documentation quality" I would start with a checklist: - is it complete and consistent - is there a description to every important piece - working examples ... and if this is complete, you can measure all you want, but I would start with the basics.
- dwiash 6y agoYea, i think that's correct. documentation is just another product, no different than other software. so basically you can start asking with very common user reasearch questions such as: * who would use our documentation? * what would our user need the most from our documentation?
- jayd16 6y ago
- pornel 6y agoYes! 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. :( :( :(
- oh_hello 6y agoYes, and this is a really shame. Several years ago I was able to become an iOS developer almost completely by reading through Apple's docs and then building a couple of projects on my own. I had a checklist of the programming guides to work my way through from Objective-C, to App Programming, to view controllers, and on. Over the years I found it more and more frustrating to truly understand new frameworks as the documentation changed. iOS development is now a small portion of my job and the lack of good resources is making it hard to stay up to date.
- grishka 6y agoAnd even when there's no documentation, or when it isn't enough, you can just always dive into AOSP sources and figure out whatever needs to be figured out. They've recently made this more convenient too: https://cs.android.com https://cs.android.com No such luck for iOS. Best you can do is poke at binaries with a disassembler.
- psahgal 6y agoI have been frustrated many times after stepping into a system function on iOS, only to be greeted with a mountain of assembly instructions. It was one of the first grievances I had with iOS development, coming from Android. On the other hand, it's been a great opportunity to learn how ARM works!
- saagarjha 6y agoIf you haven’t tried Hopper already, it’ll level up your reversing skills: https://www.hopperapp.com/ https://www.hopperapp.com/
- deleted 6y ago[deleted]
- artifact_44 6y agohttps://en.wikipedia.org/wiki/Inside_Macintosh https://en.wikipedia.org/wiki/Inside_Macintosh Guess these days are over...
- tonyjstark 6y agoOh yes, I remember the programming guides! When a friend of mine and I wrote the text editor Tincta we spend days to go through the typesetting, font, glyphs documents. We didn't really use it but we learned so much (we were still students and couldn't imagine how complicated all that is). Same for the maps and location APIs. You could really appreciate all the work and design that went into the APIs. Now I feel some of that information is hidden in WWDC videos but it's not the same. I also had good experience with the Android documentation, same (as the article stated) for PHP and most of Microsoft.
- pjmlp 6y agoOnly if you happen to follow Android team developers on Medium (it used to be G+) and Twitter. The documentation has lots of outdated stuff that only gets updated across Medium, StackOverflow, bug tracking comments, twitter posts, /r/androiddev.
- deleted 6y ago[deleted]