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

191–200 of 348 posts

Re: On Apple's Piss-Poor Documentation

#191

Post by auggierose »

alexashka wrote: post #148
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 quintessentia…

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

Re: On Apple's Piss-Poor Documentation

#192

Post by wlesieutre »

jjkaczor wrote: post #175
ethbr0 wrote: post #158

Earlier quoted context omitted.

Just hire Microsoft's people. Not even joking. https://docs.microsoft.com/en-us/dotnet/api/system.string.su...

For all the crap that Apple, Java and other open-source people have piled on Microsoft over the years, their developer documentation has always been very good. Yes, there are rough-edges. Back in the day, when Sun was still in-charge of Java, I had my 1-person consulting company partner with Sun and become an official "Certified Java" organization... Great, I thought - now I can get some better documentation... Sure,…

There's an old saying at Microsoft: developers, developers, developers, developers, developers, developers, developers, developers

Re: On Apple's Piss-Poor Documentation

#193

Post by gumby »

zentiggr wrote: post #186
gumby wrote: post #169

Earlier quoted context omitted.

This 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 di…

I'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 ju…

I am an iOS and macOS developer and user and it doesn't look that way to me at all. (FWIW I use their hardware because IMHO it sucks less than the alternatives; I'm no special fan).

Actually this part I agree with 100%:

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

And I assume this hardware focus is why their subscription options have been a mixture of mediocre and worthless.

But this point, while a common trope (and even with a name, "sherlocked"), I have't really seen it much in practice, especially since OS X rolled around:

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

I haven't seen much evidence of this in the real world. Even in the case of the Sherlock app they made a more powerful tool and still left room for third parties. They don't make much on their own software and their MVPs really are basic.

Apart from a few marquee apps in the photo/video space they don't really have a big app effort as far as I can tell from outside. I don't know how good those apps are either.

Re: On Apple's Piss-Poor Documentation

#194

Post by merb »

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…

> I never liked Ballmer, and really never liked the win APIs

actually WinRT is really good. unfortunatly they are barely widespread and probably are not that much used.

C# api docs: https://docs.microsoft.com/en-us/uwp/api/?view=winrt-19041

Re: On Apple's Piss-Poor Documentation

#195

Post by dariosalvi78 »

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…

> In terms of quality of products they still are best in their respective class IMHO.

yeah, like the keyboard of the laptop I'm writing from...

Re: On Apple's Piss-Poor Documentation

#196

Post by gumby »

samatman wrote: post #190
gumby wrote: post #169

Earlier quoted context omitted.

This 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 di…

No, but I would staunchly argue that Keynote is better than PowerPoint for making and giving presentations. Apple cares about presentations, and is lukewarm at best about making documents and running spreadsheets. It shows.

You can do a lot more with powerpoint though the results are pretty unattractive, but that doesn't matter to me.

Keynote still feels like an MVP though the results do look a lot better.

I don't think the presenter tools are any better or worse on either system.

Re: On Apple's Piss-Poor Documentation

#198

Post by trynewideas »

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

Re: On Apple's Piss-Poor Documentation

#199

Post by JAlexoid »

heavyset_go wrote: post #100
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…

Apple figures developers will still pay them $99/year even if they provide them with poor documentation, and unfortunately, it looks like they're right.

Since developers are no longer geeks building "cool stuff in garages", but people who "make flappy bird" - you're not getting away from that $99.

Re: On Apple's Piss-Poor Documentation

#200

Post by masklinn »

trynewideas wrote: post #198

The 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 th…

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

Post reply on HN