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

321–330 of 348 posts

Re: On Apple's Piss-Poor Documentation

#321

Post by dantiberian »

habosa wrote: post #320

Disclaimer: I work in Developer Relations at Google. At most large tech companies (Google, Microsoft, etc) the documentation is the responsibility of the Developer Relations team. Apple has always been an outlier: they never had a Developer Relations team at all. I've recently seen some job postings for DevRel @ Apple, but this is super new.

> Apple has always been an outlier: they never had a Developer Relations team at all.

Not sure if that is accurate, I just did a quick search for “Apple Developer Relations” on LinkedIn and found a bunch of people who’ve been in Developer Relations or Worldwide Developer Relations at Apple for 5 or 10 years or even longer.

Re: On Apple's Piss-Poor Documentation

#322

Post by Cthulhu_ »

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?

Same; there's so much important information in the WWDC videos, and part of me wanted to watch them all when I was still doing iOS development. But I can't watch videos, I don't have the attention span, and sitting to watch / listen just makes me go to sleep.

It's a me thing, not down to the presenters or anything. But all that I ask is documentation and / or blog posts.

I hope that anyone that is making a presentation also writes down the contents as a blog post and/or documentation. Please. For examples, Go's blog is pretty good (although there too one is often pointed at a presentation or slide deck for certain subjects)

Re: On Apple's Piss-Poor Documentation

#323

Post by neop1x »

simonw wrote: post #217

The difference between https://developer.apple.com/documentation/photokit/phphotoli... and its replacement https://developer.apple.com/documentation/photokit/phphotoli... is pretty damning.

It looks like a lot of this mess started with Swift introduction. While Swift is cool and everything, it causes lots of confusion. Not only that documentation is not in sync but also many existing training materials ate in ObjC, there is legacy ObjC code and libraries. It's like they flushed all their ObjC history for this shiny modern experiment which may pay off long term but was quite rushed.

Re: On Apple's Piss-Poor Documentation

#324

Post by longnguyen »

Reading this post and I'm feeling incredibly lucky being a Qt/QML developer. Qt documentation is _very_ good. It covers most of questions you might have. And if you encounter some edge cases or obscure APIs, Qt Forum is very helpful with lots of Qt veterans there.

Re: On Apple's Piss-Poor Documentation

#325

Post by nicholassmith »

longnguyen wrote: post #324

Reading this post and I'm feeling incredibly lucky being a Qt/QML developer. Qt documentation is _very_ good. It covers most of questions you might have. And if you encounter some edge cases or obscure APIs, Qt Forum is very helpful with lots of Qt veterans there.

As someone who used to do a lot of Qt and iOS development work it was always very apparent that people cared about the docs at Qt way more than Apple. There was definite areas that weren't quite as well covered, but overall the consistency was very high.

They seem to understand that if it's not well explained it's no going to be used, and then your project is going to die off.

Re: On Apple's Piss-Poor Documentation

#327

Post by elijahparker »

pak9rabid wrote: post #146
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?

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.

Agreed -- and the examples in the user comments were invaluable to me way back when I was getting started.

Re: On Apple's Piss-Poor Documentation

#328

Post by _qulr »

lmm wrote: post #318
Polylactic_acid wrote: post #309

Earlier quoted context omitted.

Basically. What are you going to do? Not release your app on apple devices? No, you will do whatever it takes to work it out yourself.

It might even be in their interests to drive away all but the most dedicated developers. After all, they have more apps than they'll ever need, the problem is always quality.

> the problem is always quality

But writing quality apps requires quality API documentation. I don't know how developers fumbling around in the dark can result in quality apps.

Being "dedicated" to Apple platforms is not the same as being dedicated to quality.

Re: On Apple's Piss-Poor Documentation

#329

Post by jiveturkey »

JBiserkov wrote: post #313
delfinom wrote: post #138

Earlier quoted context omitted.

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.

Absolutely! Have you seen this (interactive) article by the New York Times? It's unbelievable. https://www.nytimes.com/interactive/2019/09/09/technology/ap...

I found it to be believable.

Jokes aside, the point would be more compelling if the Apple apps at the top of the list all were competing against the apps being searched for, and if they included searches for apps that didn't provide functionality Apple did. The algorithm as I see it from the article is that the #1 popular app comes first. Of course Apple takes the top spot ... this is unfortunate winner-take-all promotion that in fact the entire software industry actually wants regardless of what they say or gripe about on medium (only upstarts complain, which ceases the instant they make it big).

So, then the #2-#k spots are apps by the same maker, which both serves to help the user discover other apps they mightn't have otherwise searched for (promoting use and engagement, and the app ecosystem per se), and helps persist the winner-take-all business model. By only promoting apps by the same manufacturer it maintains some odd definition of relevance.

Then after a run of same-manufacturer apps, we get back to #k-#n organic results. The user can very obviously and very easily pick out the fact that up to #k is pushing discovery, and that below there are the results they wanted. It's actually not a big deal (actively harmful) because of the irrelevance of the #2-#k results.

So, if they had bothered to include information on apps that Apple doesn't compete against (instead of producing a 1-sided story), for which there is a manufacturer who produces a very wide variety of apps, I wonder if you'd see the same type of results. #1 result being their super popular app for the search in question, #2-#k being other (unrelated to the search) apps by the same producer, then #k-#n organic results. Clearly most app makers are one- or two-trick ponies so wouldn't have search results like this. But surely there are some?

The point is, as written, it's a hit piece.

Re: On Apple's Piss-Poor Documentation

#330

Post by chromanoid »

StillBored wrote: post #77
chromanoid wrote: post #67

Earlier quoted context omitted.

Did you ever look at the Windows API documentation?

Yes, and I know the complaints. Lets look at https://docs.microsoft.com/en-us/windows/win32/api/synchapi/... Function description, supported version information, header-file and library file information, meaningful return code documentation, links to an overview of the system wait behaviors, documentation about what happens in low power situations, links to example code using the function, differences in behavior bet…

Arr, sorry I misread your comment. I am on your side when it comes to Windows API. But I am not sure if it's a thing of the past. Imo Microsoft is pretty good when it comes to documentation. The way of presentation can be improved, but I really appreciate it. I think it's a culture thing and that culture seems to be different within Apple... I think this is also visible when it comes to their app store policies....
Post reply on HN