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

21–30 of 348 posts

Re: On Apple's Piss-Poor Documentation

#21

Post by ChrisMarshallNY »

wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

SwiftUI's docs are a nightmare.

Here's a pretty damn cool app: https://swiftui-lab.com

Re: On Apple's Piss-Poor Documentation

#22

Post by cameronh90 »

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...

"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.

Re: On Apple's Piss-Poor Documentation

#23

Post by ChrisMarshallNY »

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/concrete-galoshes/

Re: On Apple's Piss-Poor Documentation

#24

Post by wlesieutre »

ChrisMarshallNY wrote: post #21
wlesieutre wrote: post #2

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

SwiftUI's docs are a nightmare. Here's a pretty damn cool app: https://swiftui-lab.com

Excellent, 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

Re: On Apple's Piss-Poor Documentation

#25

Post by psahgal »

mtc010170 wrote: post #17
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'm curious who maintains the Android docs. Is it all open source? Is any of Apples?

Based 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/. (Google maintains the Android developer site.)

Re: On Apple's Piss-Poor Documentation

#26

Post by _qulr »

jjice wrote: post #4

I 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.

You can find some good Mac/ObjC docs in the archive: https://developer.apple.com/library/archive/navigation/

Re: On Apple's Piss-Poor Documentation

#27

Post by david-cako »

Apple 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.

Re: On Apple's Piss-Poor Documentation

#28

Post by psahgal »

tmpz22 wrote: post #12
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…

My 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.

I 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.

Re: On Apple's Piss-Poor Documentation

#29

Post by musha68k »

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 saying “no” often enough anymore.

Re: On Apple's Piss-Poor Documentation

#30

Post by dkdbejwi383 »

spiderfarmer wrote: post #19
tobr wrote: post #13

I 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 d…

I 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.

This also also having a good sandbox environment and helpful test data that allows you to rapidly iterate with confidence.
Post reply on HN