5 ms·

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 v

• 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 ago
    It'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 ago
      There are no examples.
      • zapzupnz 7y ago
        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]
        • jrumbut 7y ago
          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.
          • rurp 7y ago
            In 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 ago
            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/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
  • Vomzor 7y ago
    A 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 ago
      Oh 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 ago
        Sadly, 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 ago
      And 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 ago
        Can 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 ago
    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.
    • 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.
• tompetry 7y ago
  Bingo