Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Apple Developer Documentation Is Missing

v4.chriskrycho.com

Post reply on HN
Print view View original

361–370 of 400 posts

Re: Apple Developer Documentation Is Missing

#361

Post by balls187 »

chriskrycho wrote: post #66
balls187 wrote: post #60

My issue with this is that the developer is comparing his experience with Apple's documentation over a few months, with his anecdotal experience over 4 years. Part of gaining experience with a platform is the ability to source answers to technical questions effectively, including how to use official documentation effectively.

I'm extremely comfortable reading documentation for a very wide variety of platforms, languages, etc. (The first software I ever wrote was Fortran via `gfortran`. Trial by fire!) It's not just me. This is just straight-up absent : https://nooverviewavailable.com/swiftui/ As I noted in the post, I'm getting by anyway … but it's more work than it needs to be, and more work/worse state of docs than other ecosystems I've…

My comment wasn't about your comfort level. It was about comparing your experience 4 months in, to your experience 4 years in, anecdotally.

Re: Apple Developer Documentation Is Missing

#362

Post by zapzupnz »

jrumbut wrote: post #353
zapzupnz wrote: post #343

Earlier quoted context omitted.

There's no need for examples because initializing objects/structs is such a basic feature of both languages that Apple supports, it should be taken as read that the reader knows how to do it. CIColor.init(red: 0.0, green: 1.0, blue: 0.0, alpha: 1.0) [[CIColor alloc] initWithRed:0.0 green:1.0 blue:0.0 alpha:1.0]

Need may be too strong a word, but I've never seen documentation suffer because there were too many high quality examples. Great documentation uses those examples to shine light on other features that go nicely with (in this case) CIColor or to highlight the right way to do common tasks.

Yeah but, again, we're talking about an initializer. An initializer doesn't need an example other than on the language's documentation page for initializers.

The comparison given was totally unfair, as pointed out by another user. Let's look at something more similar to LINQ's Distinct function.

Here's the Collection Types page from the Swift book: https://docs.swift.org/swift-book/LanguageGuide/CollectionTy...

Here's the examples from the API page for Swift's Collection type: https://developer.apple.com/documentation/swift/collection

Or for Sequence, also full of examples: https://developer.apple.com/documentation/swift/sequence

Re: Apple Developer Documentation Is Missing

#363

Post by computerex »

gatherhunterer wrote: post #333
computerex wrote: post #329

Earlier quoted context omitted.

https://www.engadget.com/2010/06/24/apple-responds-over-ipho... https://9to5mac.com/2019/02/11/italian-apple-homepage-to-add... https://www.theverge.com/2017/12/28/16827248/apple-iphone-ba... https://www.theinquirer.net/inquirer/news/3032188/apple-face... These is just a very small subset of incidents with Apple where Apple failed to right their wrongs and was ultimately forced to do so by public and or legal pressur…

Your point being? I said nothing that is contradicted by your comment.

> Your point being? I said nothing that is contradicted by your comment.

You said this in reply to the parent:

> I don’t know how you convinced yourself that Apple is more interested in being aloof than in making changes that would help them make money but that belief is just as ridiculous as the belief that they are altruistic.

I gave many examples of Apple not willing to make changes to improve user experience. There are many more examples that I haven't yet mentioned.

Re: Apple Developer Documentation Is Missing

#364

Post by computerex »

zapzupnz wrote: post #362
jrumbut wrote: post #353

Earlier quoted context omitted.

Need may be too strong a word, but I've never seen documentation suffer because there were too many high quality examples. Great documentation uses those examples to shine light on other features that go nicely with (in this case) CIColor or to highlight the right way to do common tasks.

Yeah but, again, we're talking about an initializer. An initializer doesn't need an example other than on the language's documentation page for initializers. The comparison given was totally unfair, as pointed out by another user. Let's look at something more similar to LINQ's Distinct function. Here's the Collection Types page from the Swift book: https://docs.swift.org/swift-book/LanguageGuide/CollectionTy... Here'…

Here's a counter-example that someone else pointed out: https://docs.microsoft.com/en-us/dotnet/api/system.drawing.c...

It's very comparable and highlights the differences and lack of detail in Apple documentation well.

Re: Apple Developer Documentation Is Missing

#365

Post by topherPedersen »

mmusson wrote: post #144
mmusson wrote: post #131

When I first learned iOS ten years ago I thought the documentation was outstanding. It had good API level documentation as well as a large number of guides that showed the right way to use the API to implement particular features. I recently returned to the platform and my experience is very much like the parents. The documentation appears to be almost completely missing. The built-in documentation does not appear to…

I have discovered that the previous documentation is still available in a “documentation archive” complete with banner warnings about how it is out of date and unsupported. It is almost impossible to find topics except by using google search. Newer functionality is missing and some of it is no longer accurate, but it is better than nothing.

I've had to resort to referencing the documentation archive before as well. While the new docs are certainly prettier, the old docs were much more substantive.

Re: Apple Developer Documentation Is Missing

#366

Post by Austin_Conlon »

perfectstorm wrote: post #184

So much this. The other day i was trying to look up documentation for Swift’s KVO and i couldn’t find one. I know there’s a KVO API that accepts a closure but i just couldn’t find where it is. smh. Apple used to link sample code with pretty much all the big APIs but they no longer do that. If you want to see how an API is used or see the best practices you’re better off checking stackoverflow.

When I learned that you could filter by sample code in the bottom left search box of Xcode's documentation window, it made sample code a lot more discoverable for me. Of course that's far from ideal though, and they should be linking to sample code more in the documentation.

Re: Apple Developer Documentation Is Missing

#367

Post by jxramos »

bob1029 wrote: post #305
Shank wrote: post #153

Maybe I'm the only one, but when I start looking into a project, I start at the API docs and work from there. I really need to know if key features I want are viable on the platform or not. If I want to use an accessibility API to, in a supported way, read all of the items in every menu in the menu bar, how do I do that? Is it supported? Is there a set of best practices I should follow? The problem with not documenti…

You are not the only one. My most recent experience with Apple's documentation (regarding some iOS 13 API concern), left me with a sense of impending doom and hopelessness. After about 5 minutes I gave up and went back to playing the google/stackoverflow search game. I have become very addicted to the quality of Microsoft's documentation for things like .Net Core & C#, and have found it virtually impossible to tolera…

At some point, especially after working there briefly, I came to the conclusion that Apple leans more heavily as a hardware company. They do great hardware integration and great work with connectivity and device ecosystems. However they are not a software company, and are not too keen on things being DX (developer experience) oriented.

Re: Apple Developer Documentation Is Missing

#368

Post by m463 »

adonese wrote: post #272
no_wizard wrote: post #61

I actually agree whole heartedly with the intentions behind this article. I find Apples documentation to be incomplete and not nearly as detailed as I think it should be. I think that personally it’s not all that well organized either. My minimum standard for good documentation has and always been Python’s[0]. While no documentation is perfect, I think they mostly get it right by providing good explanations and examp…

Sometimes i think python's docs are very verbose. Check for example argparse[1]! GO docs are quite very neat and helpful though. [1]: https://docs.python.org/3/library/argparse.html

argparse is a heavily used but somewhat complicated library. I use it in every command line utility I write in python.

I usually search or scroll that page until I get to the feature I'm interested in. I like that it has plenty of examples.

Re: Apple Developer Documentation Is Missing

#369

Post by kalleboo »

Vomzor wrote: post #347
bob1029 wrote: post #305

Earlier quoted context omitted.

You are not the only one. My most recent experience with Apple's documentation (regarding some iOS 13 API concern), left me with a sense of impending doom and hopelessness. After about 5 minutes I gave up and went back to playing the google/stackoverflow search game. I have become very addicted to the quality of Microsoft's documentation for things like .Net Core & C#, and have found it virtually impossible to tolera…

A better example would be: - Apple: https://developer.apple.com/documentation/coreimage/cicolorc... - Microsoft: https://docs.microsoft.com/en-us/dotnet/api/coreimage.cicolo...

Oh god that's both hilarious and sad at the same time. Maybe Apple should contract Microsoft to write their own documentation for them?

Re: Apple Developer Documentation Is Missing

#370

Post by pjmlp »

arcticbull wrote: post #310
verletx64 wrote: post #309

Earlier quoted context omitted.

Seriously though, in Europe the Algorithmic style interview is not the norm, by and large

Interesting, what's the process there like?

Plain old style interview, you get through HR, get a couple of interview rounds with people from different departments, discuss with them several subjects somehow related to work, positive and negative experiences across your career, what would you do if X happens,....

If you happen to do coding exercises at all, they are just basic tasks like implement a linked list data structure, count the number of words on a file and such.

Answer some trivia about the language you are supposed to use, e.g. when should you use a struct in C#.

Luckly only startups over here are somehow into SV hiring culture, which still leaves plenty of others with job offers available.

Post reply on HN