Hacker News Reader

Comment by Shank | Hacker News Reader

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 documenting things is that developers like me are turned off before we start. I don't want to bend the platform so far that it breaks. I want the limits. I'm tired of reading stories about apps being pulled for using private APIs, or breaking in future versions because they're removed. I want to do things in a supported way so I can make everyone happy.

Right now, I can't even see the boundaries of what's possible, because nothing is documented. I don't even want to try to write for Apple platforms, because it's entirely inscrutable and unpredictable.

View on HN

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

Exhibit B:

https://developer.apple.com/documentation/coreimage/cicolor/...

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.

There are no examples.

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.

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.

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

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.

A more fair comparison for B is probably https://docs.microsoft.com/en-us/dotnet/api/system.drawing.c.... Still illustrates the point, it's more informative.

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?

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

Apple deployed a new documentation system, and no one stopped to make sure all the "old" stuff got translated through.

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.

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.

His point is that none of those things actually tell you about the class, it’s just theater. If you want to know what it really does, you need to look at the source code, that’s where the truth lies.

I disagree. The images showed me what it does, or at least gave me an idea what it would do.

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.

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

Bingo

Reply on news.ycombinator.com