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

91–100 of 348 posts

Re: On Apple's Piss-Poor Documentation

#91

Post by orangefarm »

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 value of their platform. It looks like a no-brainer to me to invest some resources into this to improve the current state of affairs.

I must be missing something here...

Re: On Apple's Piss-Poor Documentation

#92

Post by Austin_Conlon »

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?

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.

Re: On Apple's Piss-Poor Documentation

#95

Post by draw_down »

blinkingled wrote: post #9

I have been trying to optimize a initContainer written in NodeJS and one of the experiment I am trying out is to rewrite it in .NET Core and Microsoft's documentation has been pretty good - it is clear, well organized, gives you examples for each API and there are how-tos for things that people typically care about - the architecture docs linked from here for e.g. https://docs.microsoft.com/en-us/dotnet/ API docs exa…

I'm not so sure about that last part. My guess would be that this is down to the difference in incentives between an open-source project and a profitable enterprise. In such a way that we may even expect this to be the common case, rather than an anomaly.

Every doc writer Apple hires has to go on a P&L statement somewhere, their existence must be justified every quarter or so, etc. As others have noted, associating this work with the value it generates is notoriously difficult. Of course, some companies may have the kind of culture that understands the value of this work and keeps them around, but open-source projects can accept contributions from whoever offers them without regard for such bureaucratic concerns.

Basically, if you write some docs for my open-source project I don't need to pay for your healthcare insurance. The barrier to entry may also be lower for the same reason- if you write some docs, the pull request can be simply merged in. Hiring an employee is a much more involved affair than adding a contributor to the Contributors list in Github.

Re: On Apple's Piss-Poor Documentation

#96

Post by on_and_off »

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…

stupid question : but is there any specific reason why swiftui is not open source ?

I am working with jetpack compose these days and it is both open source and documented. I am not sure how I would work with it without that, it is quite a big departure from the legacy ui api.

Re: On Apple's Piss-Poor Documentation

#97

Post by xbar »

tonyjstark wrote: post #69
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 wholeheartedly agree. The documentation is sparse and 3rd party tutorials have to be recent. That's why I still hold back for adoption. Paul Hudson has really good material but I wish I could just leave a tab open with the official documentation and be prepared for most challenges. OTOH, things like Core Audio where never really well documented. For learning Swift I recommend https://www.swiftforgood.com , no affil…

Agreed. Great content. Of course, there is no excuse for Apple's chronic underinvestment in Documentation.

Re: On Apple's Piss-Poor Documentation

#98

Post by grishka »

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.

Re: On Apple's Piss-Poor Documentation

#99

Post by mrtksn »

ProAm wrote: post #82
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…

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

That actually sounds good. When you pay for something it implies that you might stop paying for the thing if you’re not happy which means the seller is likely to work hard to make you happy.

I would love to have paid version of most of the apps/sites I use. Not ad-free subscription but paid version where I can be the unhappy customer when I am unhappy.

Re: On Apple's Piss-Poor Documentation

#100

Post by heavyset_go »

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