25 ms·
On Apple's Piss-Poor Documentation
- wlesieutre 6y agoI’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 Medium posts because something from before WWDC 2020 might no longer be useful. Or maybe it is. 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.
- wlesieutre 6y agoI 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 reconciling two years. The Landmarks tutorial is also very well done as a starting point. But a tutorial isn't a substitute for documentation. https://developer.apple.com/tutorials/swiftui/ https://developer.apple.com/tutorials/swiftui/
- pornel 6y agoI hate that WWDC videos have essentially replaced docs. Videos have to be shallow, and code on slides has to be short. This medium is fine to sell an idea, and to give a high-level overview of how it works, but there's no way to include as much information as written documentation would. Here's a TED talk on Thorium reactors. Why aren't you running them yet?
- njhaveri 6y agoI also really dislike that WWDC videos are now the de-facto documentation. It must be a lot of work to put them together – I wish they'd just write a doc instead. Would be way faster to read, search, etc. and could probably go into much greater depth.
- andromeduck 6y agoExample programs would be nice too.
- sixstringtheory 6y agoMany of them do come with sample code, but like the content of the sessions themselves, they age out very quickly.
- an_opabinia 6y agoYeah but on the other hand, I'm sure they look at the vibrant 3rd party tutorial content pipeline as evidence that they're doing the right thing.
- Austin_Conlon 6y agoGlobal search for all WWDC transcripts also isn't good on the website, you now how to reveal the transcript for each individual result after you search. In the Apple Developer app (where I would've expected a better user experience) it's not even possible.
- wool_gather 6y agoTry out https://asciiwwdc.com https://asciiwwdc.com next time you need this.
- pak9rabid 6y agoFor all the hate it gets, I think the way PHP does their documentation is ideal. Easy to search for what you need, it recommends other, similar classes/functions, gives a good description of the inputs and what something is expected to return. Then, in addition to that, there's the user-supplied examples and commentary to help further clarify things. I really like the model they went with.
- plorkyeran 6y agoI 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.
- jonhendry18 6y agoUnfortunately there's bits of information that are important and only ever appear in the WWDC videos.
- plorkyeran 6y agoThere's also a lot of useful information that has only ever appeared in Twitter conversations between Apple developers but I wouldn't call that documentation either.
- deleted 6y ago[deleted]
- elpakal 6y agoThey have an `API Changes: Hide/Show` thing on their documentation (on the right, top) that I think is new fwiw. https://developer.apple.com/documentation/swiftui/progressview?changes=latest_major https://developer.apple.com/documentation/swiftui/progressvi...
- ChrisMarshallNY 6y agoSwiftUI's docs are a nightmare. Here's a pretty damn cool app: https://swiftui-lab.com https://swiftui-lab.com
- wlesieutre 6y agoExcellent, thanks for this! Most recent post is "Attributed Strings with SwiftUI" which is something I was wondering about. There's plaintext TextEditor view, but for rich text editing the impression I've gotten is to either fall back to something in UIKit or do it in a WebView. Will check this post out tonight, it might not change anything but I'd at least like a better idea where things stand in SwiftUI. Props to Apple on this one, TextEditor has a real docs page. But it's only for plain text, sadly: https://developer.apple.com/documentation/swiftui/texteditor https://developer.apple.com/documentation/swiftui/texteditor
- terhechte 6y agoYeah, for rich text you need to wrap a UITextView, there's currently no other way to do that. Also, if you have a large amount of text, TextEditor won't cut it either. Even displaying rich text (non editable) is a wee bit tricky and severely under documented.
- lukeh 6y agoYeah, the sizing thing is a bit of a pain as the creates visible content fitting artefacts when contained in a list or stack.
- jamil7 6y agoFor a small app I recently just wrapped SlateJS in a webview and passed json back and forth. Slate is pretty nice but it would be nice to use a native solution.
- mhh__ 6y agoHow does it compare to Unreal's, I wonder. Seems to have the same problem, third party (Video, bleugh) tutorials.
- deleted 6y ago[deleted]
- tonyjstark 6y agoI wholeheartedly agree. The documentation is sparse and 3rd party tutorials have to be recent. That's why I still hold back for adoption. Paul Hudson has really good material but I wish I could just leave a tab open with the official documentation and be prepared for most challenges. OTOH, things like Core Audio where never really well documented. For learning Swift I recommend https://www.swiftforgood.com https://www.swiftforgood.com, no affiliation (also there Paul Hudson wrote the chapter about SwiftUI).
- xbar 6y agoAgreed. Great content. Of course, there is no excuse for Apple's chronic underinvestment in Documentation.
- krtkush 6y ago> and always looking at dates on Medium posts While I'm not an iOS dev I have seen a trend where people have stopped putting in dates of their coding tutorials.
- ProAm 6y ago> 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.
- mrtksn 6y agoThat actually sounds good. When you pay for something it implies that you might stop paying for the thing if you’re not happy which means the seller is likely to work hard to make you happy. I would love to have paid version of most of the apps/sites I use. Not ad-free subscription but paid version where I can be the unhappy customer when I am unhappy.
- grp000 6y agoThat would make sense if documentation were a standalone product, but it's completely complementary to the language, so that doesn't make any sense.
- Ronsenshi 6y agoAlready a thing: https://apps.apple.com/us/app/a-companion-for-swiftui/id1485436674?mt=12 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.
- doyouevensunbro 6y agoIt’s because engineers don’t want to write documentation, and if you don’t force it this is the result.
- piva00 6y agoA trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.
- lostcolony 6y agoI'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.
- grimjack00 6y agoYou mean you can't figure things out from "public Session getSession(String, String, String, String, String)"?
- andi999 6y agoWe tried to buy some mechanical equipment which can be steered by a computer API. I asked for the doc beforehand. Got something like your example (10 pages of C header). I asked any better docs? Answer:'a real programmer would know how to use this' - well somehow they didnt manage to sell the device to us. Later they managed to email the comprehensive docs (which existed!), but we alread spent a much larger amount (without regrets) to the competition.
- wlesieutre 6y agoOn the SwiftUI side, you might go digging in these docs for Previews, which are one of its biggest selling points: https://developer.apple.com/documentation/swiftui/previews https://developer.apple.com/documentation/swiftui/previews Take 30 seconds to read through that and the linked pages (that's all the time it will take) and see if you could figure out how to use a PreviewDevice to make your preview show a particular device. It will tell you all the ways to initialize a PreviewDevice struct (from many different varieties of String), but you'll have no fucking idea what to do with that object. And here's an actual code sample, via Paul Hudson: struct ContentView_Previews: PreviewProvider { static var previews: some View { Group { ContentView() .previewDevice(PreviewDevice(rawValue: "iPhone SE")) .previewDisplayName("iPhone SE") ContentView() .previewDevice(PreviewDevice(rawValue: "iPhone XS Max")) .previewDisplayName("iPhone XS Max") } } } It turns out what you need to do is pass the PreviewDevice instance into a previewDevice modifier that you've applied to your view inside a struct adhering to the PreviewProvider protocol. I don't think this docs page even mentions that the previewDevice modifier exists, let alone how to put any of these pieces together to configure and display a preview. You can find how to do this in tutorials elsewhere on Apple's site. But you can't find it in their documentation for Previews, because it's a bunch of automatically generated pages of function signatures with no explanation.
- Austin_Conlon 6y agoIt needs to have more conceptual articles with code listings like this https://developer.apple.com/documentation/swiftui/managing-model-data-in-your-app https://developer.apple.com/documentation/swiftui/managing-m....
- wlesieutre 6y agoYes please. Finding a “see also” link to one of those is the best, because you know it will actually show you how to use it. Otherwise you’re probably on your own. For example, Previews are one of SwiftUI’s major features. Here’s its docs page: https://developer.apple.com/documentation/swiftui/previews https://developer.apple.com/documentation/swiftui/previews You could read through that and all of the linked pages and still have no idea how create a preview. Want to preview it on a particular device? Well, I can see there’s a PreviewDevice, it’s initialized from various kinds of strings, and absolutely no information on how to apply it. Turns out this is a SwiftUI modifier that you chain off of your view inside the struct that adheres to the PreviewProvider protocol. See example here: https://www.hackingwithswift.com/quick-start/swiftui/how-to-preview-your-layout-in-different-devices https://www.hackingwithswift.com/quick-start/swiftui/how-to-... Could you construct that example from having read the documentation? I doubt it.
- on_and_off 6y agostupid question : but is there any specific reason why swiftui is not open source ? I am working with jetpack compose these days and it is both open source and documented. I am not sure how I would work with it without that, it is quite a big departure from the legacy ui api.
- saagarjha 6y agoProbably because it’s a competitive advantage for Apple to keep to themselves.
- on_and_off 6y agoI wonder how much of an advantage it is practice ? It is one such toolkit among others, like React or Compose. It is different from making the whole OS open source. I guess that since the benefit would be to make third party devs job easier, the incentive is not that great for apple .. devs will write mobile apps even if they have to write them in assembly.
- heavyset_go 6y agoApple figures developers will still pay them $99/year even if they provide them with poor documentation, and unfortunately, it looks like they're right.
- leptons 6y agoMicrosoft: Developers! Developers! Developers! Apple: Fuck off Developers!
- sk5t 6y agoApple: There's no official documentation for this, but here's a haughty forum response from an unaffiliated volunteer sycophant directing you to the extant superficially-related documentation.
- JAlexoid 6y agoSince developers are no longer geeks building "cool stuff in garages", but people who "make flappy bird" - you're not getting away from that $99.
- saagarjha 6y agoMany developers are paying for the ability to develop, not the development experience.
- Humdeee 6y agoI believe someone like Paul Hudson and the work he has done can influence a language's adoption by nearly an order of magnitude in the language's infant stages. I released a Swift 1.0 app back in 2015, and continue to provide irregular updates for it but still churns some decent income (to me). If not for him, I really don't think that spark of enjoyment would have happened. What he provided was two-fold: an enthusiast to Swift and the iOS environment, and also as a teacher and big source of documentation.
- gentleman11 6y agoUnreal engine is like that, except with fewer third party tutorials. It’s getting better but the c++ docs are almost as bad as having nothing. Some of them only have comments like “maybe refactor this” as a description, and the community wiki was taken down recently too
- ffhhj 6y agoYears ago I worked on the documentation for one of those big game engines. Previously as a "user" I suffered a lot with their physics system, and there was a big gap about its performance and best practices. After a long research in the source code and emails back and forth in the company I was able to fill those holes. My motivation came completely from within me, because absolutely no one in the company seemed interested on fixing the docs. It's the least important thing in most of these big companies.
- gentleman11 6y agoYour work is deeply appreciated
- SkyPuncher 6y agoI built a SwiftApp a few years ago. I absolutely loved working with Swift, but I could not stand the documentation. Apple was so happy to push breaking changes (without good documentation), that it made it very difficult to work with.
- rocho 6y ago> “Here’s the type signature, have fun!” My experience with Go libraries in a nutshell. One of the factors that made me abandon that language for others that for me are much more productive.
- EdwardDiego 6y agoYeah, I've found that quite often in apps/libs written for K8s in Go - wasn't sure if it was a Go cultural thing or a K8s cultural thing. If you're lucky you're getting an example or two in the README.md. The rest of the time, you're reading code to figure out the intricacies.
- rdn 6y agoAt least you can read the code, Apple's libs are closed source. You have to resort to reverse engineering techniques to fill in the documentation gaps.
- EdwardDiego 6y agoThat's a very good point. Reminds me of the bad old days of .NET (pre 2.0) where the documentation was a bit shit, and you ended up relying on Reflector to figure out wtf was going on.
- wlesieutre 6y agoAnd on a related note, I just put on yesterday's Under the Radar podcast episode, and their main topic is complaining about this same stuff. https://www.relay.fm/radar/204 https://www.relay.fm/radar/204 Makes me fell a little better knowing that professional iOS developers are having a similarly hard time with this, I was starting to feel dumb about it. I'm reading the docs, why can't I figure out how to use this?
- cvwright 6y agoAbsolutely. I’m a CS academic writing “real” code for the first time in 20 years. It’s really reassuring to hear that Marco Arment is also googling for the same SwiftUI tutorials that I keep falling back on.
- ben-schaaf 6y agoAt some point I had to read through some issues on the Firefox and Chrome issue trackers in relation to rendering on macOS. I kid you not more than once I read someone saying something along the lines of "No idea how this works, lets ask some Apple people at the next conference".
- WrtCdEvrydy 6y agoI worked at a phone company that was collapsing in market share and one of the things that always stuck out to me was: complex signing process + documentation. It seems that as you get larger in the phone space, these things are neglected until you lose market share and then they become a priority.
- zepto 6y agoApple’s signing processes have only gotten less complex from a developer point of view. But.. this article is completely correct about SwiftUI documentation.
- jjice 6y agoI had to work on a small MacOS app written in objective C at my last internship. The documentation was horrible. It was basically non-existent. I understand Swift is the primary language now, but wow, there was basically nothing in the online API reference.
- _qulr 6y agoYou can find some good Mac/ObjC docs in the archive: https://developer.apple.com/library/archive/navigation/ https://developer.apple.com/library/archive/navigation/
- Klonoar 6y agoWeirdly enough, this tends to be where Apple's docs are still good. They fall apart when you try to move on from it towards Swift & co. Granted, _finding_ the ObjC old docs can be a pain in the ass, but it's possible. I've literally found answers to some of my questions in OS release notes and nowhere else; part of being an AppKit/etc developer winds up being simply knowing how to search. Another complaint I have: depending on what era of documentation you need, you often have to qualify your searches differently - e.g, OS X vs macOS.
- psahgal 6y agoHas 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.
- layoutIfNeeded 6y agoI disagree with him on header docs. Header docs are more likely to be kept in sync with the API than whatever they have online.
- blinkingled 6y agoI have been trying to optimize a initContainer written in NodeJS and one of the experiment I am trying out is to rewrite it in .NET Core and Microsoft's documentation has been pretty good - it is clear, well organized, gives you examples for each API and there are how-tos for things that people typically care about - the architecture docs linked from here for e.g. https://docs.microsoft.com/en-us/dotnet/ https://docs.microsoft.com/en-us/dotnet/ API docs example -https://docs.microsoft.com/en-us/dotnet/api/system.collections.concurrent.concurrentqueue-1?view=netcore-3.1 https://docs.microsoft.com/en-us/dotnet/api/system.collectio... I find the Python docs and tutorials good as well. But that's to be expected for mature language/ecosystem like Python. Good documentation is a lot of work and skill and it's a thankless job for the most part. So it's really amazing when organizations / OSS communities get it right consistently.
- gregmac 6y agoMicrosoft has put lots of effort into their docs in the past couple years, and it's pretty great. Under the "Version" dropdown you can flip to see the same docs in a specific version or platform (Framework vs Core), and this is pretty helpful for porting/upgrading code, as well as coming from a Google search or Stack Overflow link -- you can easily get to the docs for the version you're working with. The other great thing they've done is published all the .NET code on https://source.dot.net https://source.dot.net, so you can dive into the code for ConcurrentQueue<T> [1] for example. I sometimes find looking at the source is a faster way to answer a specific question about how something works vs reading through several pages of documentation, where the nuance I care about is noted in a "Remarks" section which is easily missed. [1] https://source.dot.net/#System.Private.CoreLib/ConcurrentQueue.cs,18bcbcbdddbcfdcb,references https://source.dot.net/#System.Private.CoreLib/ConcurrentQue...
- blinkingled 6y agoYes, the version dropdown is a godsend especially for .NET as there are many variations - If I want to see if the API exists or is different on say .Net Core vs .Net standard this makes it a piece of cake. Also wasn't aware of the source browser - some questions are best answered by - use the source, Luke - and you might get better ideas for your own code from there :)
- dreamcompiler 6y agoApple 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.
- the_only_law 6y agoI could have sworn I read a comment on this site a few years ago where someone claimed they had to submit a support ticket in order to grt documentation for some Apple API.
- Etheryte 6y agoHaving run into something similar just recently [0], having any documentation is still (slightly) better than no documentation at all. As a stark example, macOS has a built-in sandboxing CLI tool called sandbox-exec (originally called Seatbelt), but the man page simply says it's deprecated, as far back as I could find them. Mind you, the same tool is used heavily by macOS internally, and has been around ever since Leopard [1]. Some of the best documentation is by engineers at Google, Mozilla, and others, who have just reverse engineered the thing. [0] https://www.karltarvas.com/2020/10/25/macos-app-sandboxing-via-sandbox-exec.html https://www.karltarvas.com/2020/10/25/macos-app-sandboxing-v... [1] https://www.chromium.org/developers/design-documents/sandbox/osx-sandboxing-design https://www.chromium.org/developers/design-documents/sandbox...
- saagarjha 6y agoAh, yes, sandboxing, the technically SPI interface that everyone at Apple uses and large third-party apps are tacitly told to use.
- tobr 6y agoI don’t personally have much experience with Apple’s documentation in particular, but as a general topic, increasing the quality of documentation seems to be one of the least complicated ways to improve a platform. For all the complaints people have about how hype-oriented the frontend web world can be at times, it seems clear to me that there’s usually some correlation between hype factor and simple examples/clear documentation, and that this excitement can make people move to a new technology much faster. It’s really hard to understand why Apple wouldn’t spend the necessary resources to bring developers along at a faster pace.
- spiderfarmer 6y agoI am 100% convinced that Stripe's success is at least partly due to their attention to documentation and design. Their documentation and knowledge base should be used in case studies on how to succeed as a saas.
- dkdbejwi383 6y agoThis also also having a good sandbox environment and helpful test data that allows you to rapidly iterate with confidence.
- toxik 6y agoHonestly, 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...
- cameronh90 6y ago"Code is the documentation" has to have boundaries though, or else you'd have to understand the entire system down to the instruction set in order to print hello world. Within a small/medium codebase, code is documentation is mostly okay, but for libraries and abstractions you really ought to have solid API docs.
- seemack 6y agoI 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.
- toxik 6y agoRight, that’s the thing isn’t it—sometimes an abundance of documentation is actually not a good thing. matplotlib is a good example, its documentation fails to convey the common arguments and to what degree they are universal or not; reading the code is really the easier way in the end.
- kaycebasques 6y agoI've been a technical writer for ~8 years (3 at a startup, 5 at Gooble). I don't know Apple's situation but here's my guess: > Is the documentation team too small? (Likely.) Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it's safe to say how important it is for job success) yet technical writing is almost always understaffed, no matter what size company you have. Part of it is that it's really hard to show a causal link between the docs we create and developer success. I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links at the bottom of pages, followed by an opportunity to provide freeform feedback. If developers started using those consistently and leaving testimony about how the docs helped them it would be a lot easier to prove the value of docs. This is especially true when you operate at a big, platform-level scale, as is the case on https://web.dev https://web.dev (what I work on) and these Apple API docs. Pageviews give us a rough idea of the demand for certain ideas but don't tell us anything about whether our docs are actually useful. (As an aside, in some situations it's easier to justify the technical writing team's existence; e.g. your technical writer specifically creates docs in response to support requests and the support team is able to just link customers to the docs rather than re-answering the same question over and over; or you have access to "customer's" code and are able to show that they are following the best practices / use cases you mention and avoid anti-patterns you warn about) I'll leave with a suggestion because I don't have a horse in this race. If this situation is so bad; your best option might be to create a community-managed MDN-style resource for the Apple ecosystem. I would suggest focusing it on 1) API reference documentation and 2) examples (MDN puts the examples within the API reference pages, that would probably work here). Another route could be more of what these people are already doing: make a lot of noise until Apple realizes how bad the situation is. I imagine if you can prove that you're leaving their platform because the situation is so bad, that might wake them up. (No disrespect to Apple people; I know how tough this situation is; just trying to provide constructive feedback for the broader community)
- dotnetkow 6y agoHow are the "was this page helpful?" links working out on web.dev? Are you receiving useful feedback?
- gumby 6y agoIt'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.
- delfinom 6y agoApple at this begrudgingly allows developers on their platform as they slowly make their own apps to capture all the recurring subscription revenue as the logical endgame of its walled garden.
- gumby 6y agoThis is a common, lazy argument. Apple's bundled apps are typically MVPs rather than best of breed. For me an MVP is perfectly fine for my photos and video editing while, say, for calendar and address book I use third party apps. I doubt anyone would claim that Pages or Numbers are any sort of competition for flagship apps like Word or Excel, while at the same time they don't even break new ground like google docs did (yes, I know it wasn't the first either). And perhaps Apple will get its act together on its subscription services but so far they aren't world beaters either, and never have been (going back at least as far as eWorld in the 1990s).
- zentiggr 6y agoI'm sensing an assumption that Apple needs their in house apps to be best of breed. I'm not an iOS or macOS user, but I've worked on systems over the years. It really seems like they're happy to let someone get popular to identify the niche that needs to be filled, roll an MVP to cover it, and kick out the originators with no real excuses. It's like they're still focused on hardware development and the software is just things users want to do so let's have an app only as needed to retain users, ish. Really schizoid from my point of view.
- david-cako 6y agoApple seems like they are willing to double down on SwiftUI/UiKit with Catalyst. It's getting less simple for new APIs/features but at least Apple's docs have straightforward hierarchy, even with two separate languages. Duplicate APIs usually get deprecated, like the old ALAssets photo library API. Try building an app in .NET. There are dozens of different breadcrumbs you can follow on the MS docs for varying versions of .NET, Windows, and frameworks with radically different feature parity and UI systems. Virtually everything you google when building a .NET app has to suffixed with a bunch of identifying information for which libraries and versions you are targeting. Open source has a serious advantage in this regard because communities tend to congregate around project and documentation styles that are consistent with similar projects, so you already have an intuition for how to navigate a new repo. I find React Native documentation especially easy to parse, although sometimes missing features or examples. OSs have it tough because their docs aren't tailored specifically to each framework and domain space. But maybe they should be. I think if engineers felt more like they owned their product's documentation, layout, and structure like at smaller companies, they'd be more inclined to make it just right. The SwiftUI specific tutorials are great.
- kevingadd 6y agoIs it really an asset to not have documentation for old frameworks or versions? Some people have customers on old hardware and legacy code using old APIs that they might need to integrate with, it's useful to be able to find out how that stuff behaves.
- david-cako 6y agoThat's the thing, it's all still there, but it's abundantly clear based on the pages and the list of supported OSs/platforms whether you can use it, and what the new API is. https://developer.apple.com/documentation/assetslibrary https://developer.apple.com/documentation/assetslibrary
- ansonhoyt 6y agoFor me, a large part of React Native's appeal is the docs giving me a clear path to make stuff and a fairly public development process. Sure it is also an extra layer of trouble, but I prefer the trouble I can engage with (RN) over the risk of being stranded in the unknowable (Apple).
- musha68k 6y agoI 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 saying “no” often enough anymore.
- creativityEng 6y agoThere'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.
- musha68k 6y agoI actually disagree completely. Your answer does not relate to my comment at all. This is about “Apple losing the functional high-ground” (which they clearly had at one point) in terms of design, architecture and general “DX”. All in comparison to its own previous high quality. In terms of quality of products they still are best in their respective class IMHO. Security, usability and durability are still great/good enough. This has nothing to do with marketing.
- creativityEng 6y ago>Security, usability and durability Marketing is necessary to bring up as Security and durability claims have been debunked enough times. Perception isn't reality, but similar to Tesla and Jeep owners they have high satisfaction despite objectively poor qualities. You only need to try giving your grandparents a iphone to realize usability claims are greatly exaggerated.
- 6y ago
- auggierose 6y agoI literally googled a few hours ago for "Why is Apple documentation so shit?" I mean, look at SwiftUI. Conceptually it's great, but it is also fucking buggy as hell, and I think one of the main reasons is that the developers themselves don't have good documentation available. The best documentation so far I found is this, but it's third-party: https://www.objc.io/books/thinking-in-swiftui/ https://www.objc.io/books/thinking-in-swiftui/
- deleted 6y ago[deleted]
- alexashka 6y agoSwiftUI 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 quintessential form over substance - like Apple's fucking 'butterfly' keyboards. SwiftUI is butterfly keyboards of software - wait until you want to write non-toy code with it, you'll be needing 'hack #235 by content creator #563' to make trivial features possible.
- auggierose 6y agoI'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 Flutter to the Apple ecosystem, which is great. It's especially great for people writing non-trivial software, because we don't want to spend our time on doing trivial stuff.
- alexashka 6y agoAh, 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.
- forty 6y agoWhy 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)
- tonyedgecombe 6y agoI had a choice, I decided not to develop any software for the Mac.
- fouc 6y agoHow about AWS documentation?
- OliverJones 6y agoHere's a contrarian view of this (deplorable) situation, from someone who developed for Microsoft platforms for years. The low quality of the documentation has two reasons: * Protectionism: 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. * Low commitment: The publisher (Apple) is unwilling to make the functional commitments implied by good documentation. Once the documentation says "this does that" it's harder to change "this" to do something else. In the distant past, Apple teamed up with the publisher Addison-Wesley to create and publish high quality documentation. They could certainly do so again, with A-W or O'Reilly or whoever. But they won't do it as long as they have business reasons not to. They have sufficient control over their marketplace to refuse to do this and get away with it.
- _qulr 6y ago> 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?
- delfinom 6y agoApple 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%.
- yoz-y 6y agoThere is no evidence of them doing that. Pretty much the contrary is happening.
- mikepasz 6y agoAt the very least, there is evidence of Jobs' sentiment early on to prevent 3rd party apps on Apple's platform https://www.cultofmac.com/125180/steve-jobs-was-originally-dead-set-against-third-party-apps-for-the-iphone/ https://www.cultofmac.com/125180/steve-jobs-was-originally-d...
- lordleft 6y agoA middling language with exceptional documentation can sometimes be more effective than an exceptional language with spotty documentation. The friction of acquiring sufficient context to get up and running with a language is a huge part of any technical task IMO.
- dep_b 6y agoHah the nightmare to get CallKit working. The only thing you could do is take a working example application and step by step wrap your application around it. Because taking your existing VoIP application and inserting CallKit behavior breaks in so many mysterious and undocumented ways that I really had to tell a client it wasn't going to happen with his existing application within the allocated budget. Just to get the fancy Apple call screen! And of course only FaceTime can take video calls straight into video from the lock screen, so you have to explain after it works why nobody can see each other.
- toopok4k3 6y agoI 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.
- analog31 6y agoDocs 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.
- rjsw 6y agoI still have my copies of Inside Macintosh, I consider them to be examples of good documentation. They didn't cover "class libraries". I don't have copies of whatever documentation was provided with MacApp, I do have a Think-C manual that describes their environment.
- analog31 6y agoThanks. I appreciate the counterpoint. I don't remember when class libraries became part of the Mac programming experience, but like you say it might not have been with the original docs.
- StillBored 6y agoThis 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 cases its woefully out of date because someone rejiggered an API and didn't bother to even update the inline documentation. One of the better examples of recent documentation is the core rust docs/books. Even then because the rapid release cycles no one publishes an updated "Learn Rust" book for every release, complete with boxes explaining what has changed since the last release. And god help you if you dig to far into the library ecosystem. I think this is caused by one single problem. Documentation isn't sexy and no one is paying technical writers to do the grunt work anymore. Opensource is a large part of this problem, but the commercial guys have discovered they can save a few hundred thousand a year by simply not having a documentation team, and it doesn't appear to affect them much. A couple youtube tutorials and they are done. You can see this in the evolution of software, etc. In the 1970's you got large paper manuals which covered every technical aspect of the machine/software. The users were expected to use their brains. Then in the 1980's it all transitioned to "user documentation" which was more focused on manuals that explain how to use the product, by removing the how it works part. Then in the 1990's it started moving to digital copies on disk, and the product came with a 3-4 page manual explaining how to bootstrap enough to read the rest of the docs. In the 2000's it all moved online and became more "marketing" than users guides. In the 2010's they stopped even that. Now you get a phone/software/computer your lucky to even get a piece of paper that tells you how to turn it on, charge it, or install it. Even ms doesn't publish a complete guide to all the magic swipes and keystrokes that are supported by their new shell.
- chromanoid 6y agoDid you ever look at the Windows API documentation?
- StillBored 6y agoYes, and I know the complaints. Lets look at https://docs.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-waitformultipleobjects 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.
- oumua_don17 6y agoGood documentation is one of those things whose presence is felt only when it’s absent
- kaycebasques 6y ago"When you do things right, people won't be sure you've done anything at all."
- umanwizard 6y agoAn anecdote I heard from a colleague: He was trying to find out whether it's safe to call a particular iOS API function off the main thread. Obviously, the docs didn't say. He googled a bit and found a support forum where someone had asked. An Apple engineer responded: "I don't know, but I'm looking at the code, and there sure are a lot of locks!"
- makecheck 6y agoThe particularly sad cases are when The Great API Renaming took things with older names that had good documentation and failed to copy the documentation to the new ones! Deprecations usually don’t indicate their preferred replacements either. As has been the case for years, docs may exist if you know where to look. As for SwiftUI (documentation aside) it is very powerful, even with its current API holes, and the benefits are huge. You do have to slightly rethink how you might approach certain things but ultimately SwiftUI produces shorter and cleaner code with no XIBs. (Hint: If you do end up with pages of hacky work-around code, you’re doing it wrong and should stop.) I have no doubt it will be the primary/preferred mechanism in 1-2 years.
- albertgomariz 6y agohjhjghjvjhv
- jrm415 6y agoAt least Combine is fairly easy to work with since its ideas are already familiar and Rx was so well documented.
- hughw 6y agoApple should print it all up on newsprint and fold it into paper covers, sort of like an old-fashioned phone book.
- p0nce 6y agoPeople speak about Apple excellent libraries, but a lot of these just lack in documentation. Moreover, Apple will also _remove_ documentation of API they are not favouring. And it makes sense, Apple is such a monopoly it can afford to have zero documentation, application developer would still need to get users where they are. But honestly, it's probably more that it's expensive to have good docs, so this job is being optimized out.
- jimmoores 6y agoThe only thing that might make Apple improve their documentation is if there was evidence that people started actually abandoning Apple's platforms. Currently it seems there is a never ending supply of developers ready to gamble years of their careers on Apples Terms & Conditions, and while these same people usually eventually realize that there's ultimately no money to be made, they are replaced with a new generation seeking an AppStore paved with gold. Until that stops, the docs will stay piss-poor. While I have often used a Mac for development and enjoyed it, I don't often actually develop anything for macOS or iOS because, well, why would I risk my livelihood on Apple's whim? They regularly destroy developer's lives with no thought or consequence.
- ericlewis 6y agoThere is a lot of money to be made working on iOS for big corp. hell, even small startups. You seem to allude to indie devs though, so I can agree that it would be insane to attempt to go out on your own without essentially being a startup in your own right.
- protomyth 6y agoMy other problem with Apple is the lack of PDFs. Apple has a bookstore, I should be able to download the whole of Apple's Developer Documentation on my iPad. I would prefer PDF because I cannot read a screen for hours. Plus, the examples are almost always broken and don't compile. Broken samples and videos are horrible ways to teach anything.
- jonhendry18 6y agoThey used to have PDFs linked from the documentation pages. Obviously that went away at some point.
- orangefarm 6y agoI can't get my head around why their documentation is so poor. They should have all the resources in the world to recruit people that have proven to write good documentation. If open-source projects run by volunteers can have excellent documentation (e.g. Vue), why can't Apple? Better docs mean a better developer experience which means more people want to (and are able to) develop apps for iOS which increases the value of their platform. It looks like a no-brainer to me to invest some resources into this to improve the current state of affairs. I must be missing something here...
- auggierose 6y agoI think what is happening here is that the attitude of Apple towards normal users is spilling over to its attitude towards developers. Which is obviously a big problem, if that is indeed the case.
- corty 6y agoApple 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 develop for Apple, and as soon as the stream of app updates and releases dries up, Apple might react. But not before.
- samatman 6y agoThis 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 secrecy (which is necessary) and a result of this is deep siloing of teams. How this leads to documentation being such an afterthought is murky, but I suspect that's the cause, rather than merely being complacent about their walled garden.
- Solerino 6y agorrtrtr
- justin_oaks 6y agoI wonder if there is a way to get Apple's attention. There's a lot of power in collective action. It'd be interesting to see what would happen if every developer who was unhappy with the documentation put in an email, a call, or a support ticket.
- Zelphyr 6y agoMarco 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.
- captn3m0 6y agoPHP's documentation is amazingly well done. It goes above and beyond almost everything else.
- laichzeit0 6y agoPostgreSQL’s documentation is also amazingly well done. There’s also HighCharts. But not the documentation, rather the fact that I almost never felt like I needed any. The API was just so well done that you didn’t need any. That was my experience anyway.
- jes5199 6y agoin the old days MySQL + PHP became a popular combination because they both had great docs. But Oracle has let MySQL's documentation get worse and it's no longer the best
- arthurcolle 6y agoI wanted to print out the Postgres documentation to have a physical copy and then my jaw dropped, realizing I would need to print out 7 double sided 50 page booklets if I wanted to do this! 300 https://www.postgresql.org/files/documentation/pdf/13/postgresql-13-US.pdf https://www.postgresql.org/files/documentation/pdf/13/postgr...
- megiddo 6y agoI try to explain to non-PHP devs how they live in a world of darkness and ignorance. PHP documentation is a major factor in it's long-term record.
- jes5199 6y agoIt's true! For me, PHP's docs were an amazing on-ramp to becoming a developer "I just need a function that does something like...". A lot of the language design is annoyingly inconsistent and hard to use, but even in 2005 there were clear explanations on how to make it work. As an experienced engineer, if I'm handed a well-designed but poorly-documented API, I can usually guess the intent and make it work, at the cost of working more slowly. But a junior engineer will be completely stymied by insufficient docs, regardless of how good the software design is. I guess, in summary: good docs can make up for bad code. But good code can't make up for bad docs.
- GnarfGnarf 6y agoHave 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 Win32 app to Qt (and macOS), and there is not one single Win32 API call left, except for an obscure font enumeration thing because we wanted to stay with our own PDF code instead of using Qt's.
- jes5199 6y agoI can always tell when I'm using a Qt app on my mac, because my keyboard navigation shortcuts don't work
- GnarfGnarf 6y agoThanks for mentioning that, I'll try and make sure we accommodate keyboard navigation shortcuts.
- yoz-y 6y agoThe 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.
- Klonoar 6y agoQt is not true Cocoa, even still - IIRC (and I think it was literally somewhere on this forum that I was corrected by a Qt engineer) they use the Cocoa things to handle some drawing code, but it's still their own stuff on top of that (they used to use HITheme & co before they modernized it). It's why you'll see subtle differences on things like buttons.
- ListenLinda 6y agoI'd like to point out this phenomenon is not limited to their APIs. The docs for sys admins are poor as well.
- Apes 6y ago"Poor" implies that it exists at all. For sys admins, most MacOS components are completely undocumented, or are documented with sparse copies of BSD documents from 20+ years ago.
- lostgame 6y agoI've been working on a very simple (but extremely useful) WatchOS project I'd like to keep under wraps for the time being, as I think it could certainly sell. Apple's WatchOS documentation, however; is sparse at best, barely there at worst. It's been a problem with various Apple documentation for years.
- Austin_Conlon 6y agoOut of curiosity, are you talking about WatchKit or SwiftUI?
- intricatedetail 6y agoIf developers invest a lot of time in getting to know the product, chance is they will be more dedicated to it, so that they don't feel they lost so much time. This is another predatory tactic of this company.
- rogerallen 6y agoO how the mighty have fallen! If you haven't ever done it, take a browse through the Inside Macintosh Volume I pdf here. https://vintageapple.org/inside_o/ https://vintageapple.org/inside_o/ All API documentation should aspire to be this great.
- mariodiana 6y agoI swear to the gods of Cupertino I am not trying to start a flame war, but -- Apple fanboy though I am -- I recently started taking a look at Flutter and was absolutely floored by the difference in the state of documentation between the two. Leave aside all talk of the viability of cross-platform development. That's not what I'm talking about. I'm just talking about the developer experience of working with the documentation. At my work there are two of us programming in Objective-C for our iOS apps. We lament that Apple seems to hate its developers. In my most dejected moments, I think of getting out of mobile development entirely, or diving deep into Flutter and getting a job doing that.
- bbreier 6y agoYou are totally correct- and the worst part is, it hasn't always been this way. I've been doing iOS and Android development since the days of iOS6, and for the majority of that time, I've found iOS documentation to be significantly more useful than Android's. Recently it has flipped, and it has truly come to a head in the release of iOS14, where many documentation pages still mark live APIs as Beta software. It's so frustrating, and it is so much worse knowing that the developer experience used to be so much better.
- jfim 6y ago> We lament that Apple seems to hate its developers. The joke back then (well over fifteen years ago, pre-iPhone) was that Apple is very user friendly, but that developers aren't users. It's interesting to see that that hasn't changed since then though, you'd think that with all the iPhone money they would've invested a bit of it in developer documentation. Out of curiosity, how's XCode these days? Back then it was a rather scrappy team, but it still beat Metrowerks' CodeWarrior.
- mariodiana 6y agoWell, I like Xcode. But Apple keeps making changes with every version, and some of those changes seem to be for no good reason. You get a kind of muscle memory after a while, from using your IDE. When a button is moved or removed, or a menu is changed, it adds friction to your day. Also, I got bit with this thing they did for the new ARM chips in the Macs. Our script to build a fat binary (device and simulator) for a in-house framework broke, and we couldn't add the simulator anymore. That took a lot of tracking down to fix. It's constant aggravation like that that wears on a person. Last year, we had the 3rd-party mapping software we use break, because -- as best as I can tell -- Apple changed the implementation for drawing. That was a pain in the ass to track down, too. I wasn't kidding when I wrote that I was a fanboy. But the other day I was thinking of Steve Ballmer, years ago, running around on stage like a sweaty lunatic -- "Developers, developers, developers!" I mocked him then. Now I'm sorry I did.
- alexashka 6y agoDocumentation? Apple doesn't have any tools to create it. Sorry, there isn't a single good tool for documentation, regardless of language, platform or project, in existence, today. It's frankly easier to point out what non-trash tools for rational human beings we do have, rather than don't have, because it isn't too long of a list.
- narenkeshav 6y agoI always find Apple docs to be good and with right level of information. I do not agree with that article.
- banachtarski 6y agohttps://developer.apple.com/documentation/metal/mtldevice/1433388-makecommandqueue https://developer.apple.com/documentation/metal/mtldevice/14... Here's Apple's documentation on creating a gpu command queue. https://docs.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-id3d12device-createcommandlist https://docs.microsoft.com/en-us/windows/win32/api/d3d12/nf-... Here's msft d3d12 https://www.khronos.org/registry/vulkan/specs/1.2-extensions/man/html/vkAllocateCommandBuffers.html https://www.khronos.org/registry/vulkan/specs/1.2-extensions... Vulkan for good measure. Apple is CONSISTENTLY underspecifying APIs. The docs never refer back to comprehensive guides. They don't tell me the API constraints. They don't tell me the performance implications. You may "think" Apple documentation is good, but honestly, it's bad and anyone that also programs for other platforms would arrive at the same conclusion.
- srgpqt 6y agoLook at the Elixir and Phoenix Framework if you want to see how documentation should be done. Guides and introduction : https://elixir-lang.org/getting-started/introduction.html https://elixir-lang.org/getting-started/introduction.html Elixir reference doc: https://hexdocs.pm/elixir/Map.html https://hexdocs.pm/elixir/Map.html Phoenix reference doc: https://hexdocs.pm/phoenix/Phoenix.Controller.html https://hexdocs.pm/phoenix/Phoenix.Controller.html
- ketzo 6y agoBig +1. Those docs are a big reason I found Phoenix to be so fun -- all my beginner questions were stupid easy to answer, and my more intermediate questions had guides and links to further study in the official docs.
- oriolid 6y agoI've been cursing the same problem with Objective C APIs for audio and some other stuff until I made a discovery: there's quite detailed documentation in comments in the API header files. Apple could generate documentation website from those comments if they wanted, but it seems that they don't want. Overview documentation would be nice, too, because the comments mostly cover details.
- kazinator 6y agoYou need documentation not just to get your happy case working (how do I call this?), but to know things like: 1. Know whether a good behavior you're getting is a fluke, or required. 2. If something stops working with a new release of the API middleware, is it due to their bug, or because you misused it? 3. What limitations of the API will leak through to your program? What input ranges to watch out for? 4. What unexpected situations could occur that must be handled? These won't happen if you get the happy case working, or not all of them.
- kobayashimaru 6y agoNot only that - it took me 2 weeks to sell a fucking fone because of the walled garden they..... um.... harvest
- sroussey 6y agoOMG, their docs for certificates and profiles doesn’t match error messages or xcode or their dev site where you manage them. :/
- teliskr 6y agoI agree with this completely. Apple recently required that anyone using 3rd party authentication (google, fb, etc) in their iOS app, must also provide support for Apple ID signin. That is not an unreasonable request. I was able to implement the signin without too much difficulty. However, when it came to doing a server-side validation of the signin via the Apple API; it was an absolute POS blackbox. Their documentation and server responses provided no indication of why the validation failed. I searched the docs and forums; it was clear that a ton of other people had the same problem with absolutely no clues into resolving the issue. So I just gave up on it. Total waste of time.
- ARandumGuy 6y agoI looked at the example the article links to, and it's worse than it portrays. Not only is there no information on the requestAuthorization page, but the enum type used, PHAccessLevel, also contains no documentation! Apple, how hard is it to write the different values for an enum?!?
- etaioinshrdlu 6y agoIt seems like stuff like this favors experienced developers who have seen enough to guess how things likely work. They can still get stuff done. It really hurts newcomers, or anyone in a hurry.
- trynewideas 6y agoThe bullet points ("Is the documentation team not given the time..." etc.) apply to a lot of tech companies. "politics or in-fighting" and "not considered a prerequisite for shipping" hit especially close to home. Not that it's an excuse for anything Apple does, but technical docs are an afterthought at all levels across the board at software companies, and the few places that do them well stand out much more than the many that botch them.
- masklinn 6y ago> not considered a prerequisite for shipping IME that's really the one, at none of my jobs have releases been really urgent, but writing or updating documentation was never really part of any sort of process. To the extent that it existed it was something you'd task one or two persons once in a while, but one or two not-professional-writers can't document the production of dozens of devs and do their own dev. Producing documentation is looking down upon, it's not factored in any development, it's not part of any development process, and it's not part of any training. Most people also don't enjoy writing documentation, though I couldn't say whether it's because they simply have no training / encouragement for it, or genuine primal dislike.
- imtringued 6y agoI think this old HN discussion is relevant because it shows that documentation is multifaceted and just one approach doesn't cover everything. https://news.ycombinator.com/item?id=21289832 https://news.ycombinator.com/item?id=21289832 I have often seen people complain about auto generated documentation being worse than useless when that is not the case. It's not that the documentation is poor, it's that there is a complete lack of the other 3 kinds of documentation.
- 1MoreThing 6y agoBig agree, although I think in this case even the auto-generated stuff being talked about is awful.
- simonw 6y agoThe difference between https://developer.apple.com/documentation/photokit/phphotolibrary/1620736-requestauthorization https://developer.apple.com/documentation/photokit/phphotoli... and its replacement https://developer.apple.com/documentation/photokit/phphotolibrary/3616053-requestauthorization https://developer.apple.com/documentation/photokit/phphotoli... is pretty damning.
- keyle 6y agoWow, that's a great example. I'm also very frustrated by the pretty html with absolutely no value.
- deleted 6y ago[deleted]
- revel 6y agoThis is just so.. amateur. The message this sends to me as a developer is: don't waste your time with this unless you have no choice
- neop1x 6y agoIt looks like a lot of this mess started with Swift introduction. While Swift is cool and everything, it causes lots of confusion. Not only that documentation is not in sync but also many existing training materials ate in ObjC, there is legacy ObjC code and libraries. It's like they flushed all their ObjC history for this shiny modern experiment which may pay off long term but was quite rushed.
- macspoofing 6y agoThat's just lazy. Apple, a trillion-dollar corporation, has no excuse here. Good documentation is just a function of (relatively small) monetary investment. Invest in tech writers and you'll get great documentation - that's all it takes.
- Coko 6y agoIn some cases the documentation just plain wrong. Core data can be confusing, but worse with wrong documentation. I've had an open radar about the merge policy documentation for over 3 years and nothing has happened, even after talking to a core data engineer at WWDC in 2018. These two should be the same, but see the conflicting description: https://developer.apple.com/documentation/coredata/nsmergepolicy/1690609-mergebypropertystoretrump https://developer.apple.com/documentation/coredata/nsmergepo... (in-memory changes trump) https://developer.apple.com/documentation/coredata/nsmergebypropertystoretrumpmergepolicy https://developer.apple.com/documentation/coredata/nsmergeby... (external changes trump) Same here: https://developer.apple.com/documentation/coredata/nsmergepolicy/1690607-mergebypropertyobjecttrump https://developer.apple.com/documentation/coredata/nsmergepo... (external changes trump) https://developer.apple.com/documentation/coredata/nsmergebypropertyobjecttrumpmergepolicy https://developer.apple.com/documentation/coredata/nsmergeby... (in-memory changes trump)
- hownowbrowncow 6y agoEven the videos at the latest WWDC have been really challenging. For example, the videos showing new Document Driven apps in SwiftUI never released their sample code as a lot of developers sought here: https://developer.apple.com/forums/thread/651193 https://developer.apple.com/forums/thread/651193. They really just presented a glorified demo and a few slides. And yet the old approach for Document Driven Apps is completely out of date straight from the banner page here: https://developer.apple.com/document-based-apps/ https://developer.apple.com/document-based-apps/ (https://developer.apple.com/library/archive/samplecode/ShapeEdit/Introduction/Intro.html https://developer.apple.com/library/archive/samplecode/Shape...). As mentioned in a lot of comments, there's a real desire to build apps natively but held back by bugs and the lack of entry through even sample code.
- dzhiurgis 6y agoI've recently went thru reviewing 20+ JS libraries to draw datatables. Pretty much all of them conflate API documentation with how-to documentation. You really wan't both, but API docs should always be there - you can hack them together. Listing API's in your how to's is hard to find. My favourite API docs are pptr.dev and playwright.dev (key being fuzzy search) - do anyone know what tool they use to generate it?
- atarian 6y agoApple can get away with it because the devs are willing to put up with it.
- person_of_color 6y agoDocumentation doesn't get you a promotion
- Watabou 6y agoAn example of this that I noticed just recently: Here's the doc for a deprecated `launch` method of `Process`: https://developer.apple.com/documentation/foundation/process/1414189-launch https://developer.apple.com/documentation/foundation/process.... It's deprecated, and there's no note on what the replacement should be. Xcode, however, has a hint to use the `run` method. This isn't documented anywhere. If I don't use Xcode, I wouldn't know about this replacement. And here's the replacement document for `run`: https://developer.apple.com/documentation/foundation/process/2890105-run https://developer.apple.com/documentation/foundation/process.... "No overview available". This is beyond embarrassing.
- ketzo 6y agoSay what you want about the npm ecosystem, but I've found that the most popular libraries to solve a particular problem are almost always the ones with the best documentation. It's natural selection: the ones that are easier to install/use get installed/used more often. It's to the point where I expect good documentation, and will pretty quickly discard a library if the docs don't look robust on first inspection. It's sort of bizarre to me that Apple doesn't know this, or at least hasn't acted on it.
- ccostes 6y agoI think they know it's bad, they just don't need to make it better because its their OS so they're the only game in town. Developer experience isn't why people write apps for mac/iOS, so there's not much incentive for them to invest in it.
- pjmlp 6y agoI also have to agree, now most modern stuff is only mentioned at WWDC, while the older material is only available in the archive, with its replacement being just the "header" file/module listing. I just keep saving the ones I need, because even the archive eventually deleted, e.g. Objective-C++ docs.
- pmontra 6y ago> No matter what, I’ve been banging on this drum for years. I haven’t a clue what the problem is at Apple. The problem is that they are selling a lot of iPhones despite the quality of the documentation. If bad documentation would translate into no apps and into low sales then they would write top notch documentation. They made such a huge profit instead, no wonder they don't care about this and other issues.
- chj 6y agoThey really should hire the team behind MDN.
- habosa 6y agoDisclaimer: I work in Developer Relations at Google. At most large tech companies (Google, Microsoft, etc) the documentation is the responsibility of the Developer Relations team. Apple has always been an outlier: they never had a Developer Relations team at all. I've recently seen some job postings for DevRel @ Apple, but this is super new.
- dantiberian 6y ago> Apple has always been an outlier: they never had a Developer Relations team at all. Not sure if that is accurate, I just did a quick search for “Apple Developer Relations” on LinkedIn and found a bunch of people who’ve been in Developer Relations or Worldwide Developer Relations at Apple for 5 or 10 years or even longer.
- longnguyen 6y agoReading this post and I'm feeling incredibly lucky being a Qt/QML developer. Qt documentation is _very_ good. It covers most of questions you might have. And if you encounter some edge cases or obscure APIs, Qt Forum is very helpful with lots of Qt veterans there.
- nicholassmith 6y agoAs someone who used to do a lot of Qt and iOS development work it was always very apparent that people cared about the docs at Qt way more than Apple. There was definite areas that weren't quite as well covered, but overall the consistency was very high. They seem to understand that if it's not well explained it's no going to be used, and then your project is going to die off.
- helsinkiandrew 6y agoIt's such a shame, the original Macintosh programmer manuals (from 30 years ago) - where superb. I can't remember the exact name so can't find them on the internet but they were Multi Volume A4/US Letter size, beautifully typeset and full of information.
- alphawong 6y agoTrue. But the worst thing is that they do not offer a PR system for contributor to enrich their doc like others one
- dorado3 6y agoEvery June we hear dozens of statements like "We're so excited to see what you do with X. It's so new and amazing." And yet, they barely lift a finger to help developers understand how to use X properly. SwiftUI is a perfect example. Their developer forums are apparently a place to talk to yourself. Something is deeply wrong with them and I can't tell if it is merely a case of extreme oblivious arrogance, or if they are self sabotaging, perhaps unconsciously.
- benmathes 6y agodescriptively: Apple has enough market clout so that it (implicitly) thinks developers will pay the time cost to overcome the lack of documentation and save apple the time it would take to write the documentation. The lever isn't good/bad docs, it's the market dominance apple has in controlling access to high-spend customers. Similarly, MS was notoriously hard to dev on during MS's period of market dominance. It's a lot more dev-friendly now because it doesn't dominate as much anymore.
- 72deluxe 6y agoMicrosoft's documentation is by and large far superior. My old boss used to say that Apple wasn't a developer company and I would scoff but I think it's true when you compare them to Microsoft.