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

141–150 of 348 posts

Re: On Apple's Piss-Poor Documentation

#141

Post by psahgal »

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.

I have been frustrated many times after stepping into a system function on iOS, only to be greeted with a mountain of assembly instructions. It was one of the first grievances I had with iOS development, coming from Android.

On the other hand, it's been a great opportunity to learn how ARM works!

Re: On Apple's Piss-Poor Documentation

#142

Post by SilasX »

Ronsenshi wrote: post #107
ProAm wrote: post #82

Earlier quoted context omitted.

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

Already a thing: 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.

Reminds me -- it used to be that I could plug my Macbook air into a monitor and arrange my windows, and it would return them to that position whenever I'd disconnect and come back. That feature vanished as of ~2018 and you have to buy some app to get it back.

Re: On Apple's Piss-Poor Documentation

#143

Post by dragonwriter »

qayxc wrote: post #136
munificent wrote: post #111

Earlier quoted context omitted.

> Get ready for documentation subscriptions. MSDN Library. Everything old is new again.

That's a bogus claim! The MSDN documentation has always been freely available. The subscription service included all of Microsoft's software editions for development purposes and that's what subscribers actually paid for. The documentation of software packages, APIs, and driver kits was freely available online.

> The MSDN documentation has always been freely available

No, it hasn't. It was originally available exclusively to subscribers, and only on CD. MSDN started before the web existed.

Eventually, the documentation became free on the web.

Re: On Apple's Piss-Poor Documentation

#144

Post by captn3m0 »

Zelphyr wrote: post #103

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

PHP's documentation is amazingly well done. It goes above and beyond almost everything else.

Re: On Apple's Piss-Poor Documentation

#145

Post by corty »

orangefarm wrote: post #91

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

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

Re: On Apple's Piss-Poor Documentation

#146

Post by pak9rabid »

pornel wrote: post #47
wlesieutre wrote: post #6

Earlier quoted context omitted.

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

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?

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

Re: On Apple's Piss-Poor Documentation

#147

Post by megiddo »

Zelphyr wrote: post #103

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

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

Re: On Apple's Piss-Poor Documentation

#148

Post by alexashka »

auggierose wrote: post #33

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

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

Re: On Apple's Piss-Poor Documentation

#149

Post by musha68k »

creativityEng wrote: post #134
musha68k wrote: post #114

Earlier quoted context omitted.

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

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

Troll harder.

Re: On Apple's Piss-Poor Documentation

#150

Post by Rotten194 »

selfmodruntime wrote: post #139
lostcolony wrote: post #86

Earlier quoted context omitted.

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

Rust and rustdoc (forget what it‘s called) have the same issues, sadly.

rustdoc has the ability to embed usage examples in the doc comments, and automatically test them. also module-level documentation is doable via doc comments in the module main file. rust doesn't force you to write good documentation, but the tools are all there and I often see great documentation for rust crates that was generated with cargo doc. For example the Rocket docs are full of code examples on both the module and function level: https://api.rocket.rs

I think there's something to be said for javadoc, cargo doc, etc encouraging documentation to hew closely to the structure of the code as opposed to a free-form documentation system that can include multiple pages about tasks, getting started, etc. But the vast majority of projects don't bother to set that up, and the javadoc approach makes it very low friction to add docs to existing code that probably already has comments explaining how to use it.

Post reply on HN