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

131–140 of 348 posts

Re: On Apple's Piss-Poor Documentation

#131

Post by wlesieutre »

Austin_Conlon wrote: post #87
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…

It needs to have more conceptual articles with code listings like this https://developer.apple.com/documentation/swiftui/managing-m... .

Yes 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

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

Could you construct that example from having read the documentation? I doubt it.

Re: On Apple's Piss-Poor Documentation

#132

Post by alexashka »

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

Re: On Apple's Piss-Poor Documentation

#133

Post by ansonhoyt »

david-cako wrote: post #27

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 version…

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

Re: On Apple's Piss-Poor Documentation

#134

Post by creativityEng »

musha68k wrote: post #114
creativityEng wrote: post #78

Earlier quoted context omitted.

There'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…

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.

Re: On Apple's Piss-Poor Documentation

#135

Post by andromeduck »

njhaveri wrote: post #85
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?

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

Example programs would be nice too.

Re: On Apple's Piss-Poor Documentation

#136

Post by qayxc »

munificent wrote: post #111
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.

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

Re: On Apple's Piss-Poor Documentation

#137

Post by gregmac »

CobsterLock wrote: post #54
gregmac wrote: post #20

Earlier quoted context omitted.

Microsoft 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…

Personally I keep a .NET decompiler on my taskbar. I was about to say I like being able to find all references and usages of internal variables, but I see now the site does a pretty good job. I also like directly seeing how my code utilizes the library functions (not just the .NET libraries, sometimes nuget packages too). The decompiler also removes ambiguity of "what code is actually being ran". ILSpy has worked nic…

ILSpy + LINQpad is my go-to as well, and I actually still use ILSpy more often than source.dot.net. It's nice to be able to send a link to someone else though, and the site is well done, fast, and has a great domain. :)

Re: On Apple's Piss-Poor Documentation

#138

Post by delfinom »

gumby wrote: post #76

It'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…

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

Re: On Apple's Piss-Poor Documentation

#139

Post by selfmodruntime »

lostcolony wrote: post #86
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…

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.

Re: On Apple's Piss-Poor Documentation

#140

Post by delfinom »

_qulr wrote: post #59
OliverJones wrote: post #41

Here'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…

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

Apple 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%.
Post reply on HN