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

261–270 of 348 posts

Re: On Apple's Piss-Poor Documentation

#261

Post by [deleted] »

grishka wrote: post #98
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…

And 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 No such luck for iOS. Best you can do is poke at binaries with a disassembler.

[deleted]

Re: On Apple's Piss-Poor Documentation

#262

Post by wlesieutre »

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…

And 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

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?

Re: On Apple's Piss-Poor Documentation

#263

Post by dzhiurgis »

I'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?

Re: On Apple's Piss-Poor Documentation

#264

Post by cvwright »

wlesieutre wrote: post #262
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…

And 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 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?

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

Re: On Apple's Piss-Poor Documentation

#265

Post by auggierose »

alexashka wrote: post #254
auggierose wrote: post #240

Earlier quoted context omitted.

Well, stop writing CRUD apps! That's boring indeed. How about you do some real software?

I am 'doing' real software - I saved up my money writing CRUD and quit as soon as I could afford to. What I am personally doing in no way negates the fragmentation that is present. SwiftUI is the latest contributor to never-ending CRUD hell and I am merely informing the young and impressionable, that SwiftUI is not your friend - it is your anti-cross-platform, proprietary, closed source devil spawn (being dramatic fo…

I had the pleasure to attend a talk given by Joe Armstrong. For some reason he was always looking over to Phil Wadler, apparently looking for approving nods, but there were none to be found :-)

I hear what you are saying. I also find it unfortunate that something simple like UI is so fragmented. But then again, maybe UI is not so simple after all. The current paradigm that SwiftUI copies and evolves is that of React, and it just didn't exist 20 years ago. Funny also that this new paradigm was invented for the web first. While a lot of web stuff is crappy indeed, this is one of those examples where it produced a superior paradigm that is now copied and evolved outside of web as well, for example by SwiftUI, also by Flutter.

That's just how progress looks like.

Re: On Apple's Piss-Poor Documentation

#266

Post by tonyjstark »

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…

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

Re: On Apple's Piss-Poor Documentation

#267

Post by wool_gather »

Austin_Conlon wrote: post #92
pornel wrote: post #47

Earlier quoted context omitted.

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

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

Try out https://asciiwwdc.com next time you need this.

Re: On Apple's Piss-Poor Documentation

#268

Post by analog31 »

rjsw wrote: post #179
analog31 wrote: post #74

Earlier quoted context omitted.

Docs for the 68k Mac were abysmal. There was a collection of books entitled "Inside Macintosh" that were nearly impenetrable, and only scratched the surface of the elaborate class libraries. Instructions for creating "Hello World" on the Mac were dozens of pages long. From what I've read, Jobs certainly understood the importance of software, but only great software. He didn't want the Apple ecosystem to become loaded…

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

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

Re: On Apple's Piss-Poor Documentation

#269

Post by tonyjstark »

ljm wrote: post #209
wizzwizz4 wrote: post #181

Earlier quoted context omitted.

I concur. PHP is a horrible language, but I don't hate working in it. The documentation is the reason.

I concur and add that PHP has actually evolved quite nicely, and it's horribleness is merely an outdated meme. Java is still playing catchup to the stuff PHP has added in recent years. Just because it was shit 15 years ago doesn't mean it's still shit now.

IMHO there are still some edges that drive you mad until you remember them but the documentation is really good and every release is full of improvements. Also many available frameworks and tools in PHP world are outstanding. For me PHP provides a serious Rapid to Market Edge.

Re: On Apple's Piss-Poor Documentation

#270

Post by ben-schaaf »

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…

At 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".
Post reply on HN