4 ms·
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
by bob1029 7y ago
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 tolerate reading documentation from any other vendor at this point. A completely arbitrary but hopefully obvious side-by-side comparison:
Exhibit A:
https://docs.microsoft.com/en-us/dotnet/api/system.linq.enumerable.distinct?view=netcore-3.0 https://docs.microsoft.com/en-us/dotnet/api/system.linq.enum...
Exhibit B:
https://developer.apple.com/documentation/coreimage/cicolor/1438084-init https://developer.apple.com/documentation/coreimage/cicolor/...
- lilyball 7y agoIt's unclear to me what you think Exhibit B is demonstrating. That's the documentation for CIColor.init(red:green:blue:alpha:), and it's documented. It creates a CIColor with the specified red/green/blue/alpha components. This is literally just a model object.
- computerex 7y agoThere are no examples.
- zapzupnz 7y agoThere'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]
- jrumbut 7y agoNeed 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.
- rurp 7y agoIn addition to this, many developers (such as myself) learn best by example. Seeing a new tool in use is almost always the fastest way for me to grok it.
- zapzupnz 7y agoYeah 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/CollectionTypes.html 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 https://developer.apple.com/documentation/swift/collection Or for Sequence, also full of examples: https://developer.apple.com/documentation/swift/sequence https://developer.apple.com/documentation/swift/sequence
- computerex 7y agoHere's a counter-example that someone else pointed out: https://docs.microsoft.com/en-us/dotnet/api/system.drawing.color?view=netcore-3.0 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.
- marijnz 7y agoA more fair comparison for B is probably https://docs.microsoft.com/en-us/dotnet/api/system.drawing.color?view=netcore-3.0 https://docs.microsoft.com/en-us/dotnet/api/system.drawing.c.... Still illustrates the point, it's more informative.
- Vomzor 7y agoA better example would be: - Apple: https://developer.apple.com/documentation/coreimage/cicolorcubewithcolorspace?language=occ https://developer.apple.com/documentation/coreimage/cicolorc... - Microsoft: https://docs.microsoft.com/en-us/dotnet/api/coreimage.cicolorcubewithcolorspace?view=xamarin-ios-sdk-12 https://docs.microsoft.com/en-us/dotnet/api/coreimage.cicolo...
- kalleboo 7y agoOh god that's both hilarious and sad at the same time. Maybe Apple should contract Microsoft to write their own documentation for them?
- valleyer 7y agoSadly, Apple actually does have good documentation for Core Image. It just never made it into their new system and is instead languishing in the "archive": https://developer.apple.com/library/archive/documentation/GraphicsImaging/Reference/CoreImageFilterReference/index.html#//apple_ref/doc/filter/ci/CIColorCubeWithColorSpace https://developer.apple.com/library/archive/documentation/Gr... Apple deployed a new documentation system, and no one stopped to make sure all the "old" stuff got translated through.
- hn3000 7y agoAnd the sad thing is, that there is almost no added information in the Microsoft version except for some _documentation theater_. I find Microsoft's documentation as unusable as Apple's, with the difference that nowadays I can hunt down the source code for dotnet core while Apple's source is still private.
- dgritsko 7y agoCan you explain what you mean by this? I have never heard the term "documentation theater", yet it seems like you're using it pejoratively here. The Microsoft version has a summary of the intended purpose of the class, a brief code snippet showing what its use might look like, images demonstrating the output of using the class, and lists of all available constructors, properties, and methods along with a brief description of each. If this is "documentation theater", please sign me up for more.
- jxramos 7y agoAt 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.
- eternalban 7y ago> However they are not a software company The stellar user interface that preceded industrial design dazzle was pure software. Apple does many things, and one of them is developing software. It is possibly fair to say they are no longer doing software as well as in the past.