An Example of why I think Apple’s developer documentation sucks

for anyone thinking of complaining i’m being “mean” or “unfair”, I was being *nice* here. I could have compared MS’s OS automation and PowerShell documentation to Apple’s Automation and AppleScript documentation. But why beat a dead horse?

It’s no secret I really hate Apple’s dev. docs. Because they are bad. Objectively so, and in ways that hurt new people. For example, let’s say I want to put a button in my UI. I need to know things about that item right? Here’s what you get for a SwiftUI button, from the docs page for it.

Lots of info on creating a button. In fact, almost all of the information on buttons are about some variant of init() for a button, 25 entries in all. But how do I make the text in a button. Well, that’s not actually listed, but in the initial button page, there’s a link to Label, but it seems I don’t’ always need a label, just sometimes. That’s…not helpful. I guess I should use Label only when I have a title and an icon? Well the Label page sort of helps, but not really.

You know what would be handy here? Some simple sample code with images. Nope. Doesn’t exist.

Also what are a button’s properties? What are the methods that are unique to a button? Do they exist? Well they must, because there’s this whole buttonStyle thing, let’s take a look at that, maybe there’s a list of properties there with sample co…nope. Just one shown, .bordered, and no images. So if you don’t know what a .bordered button looks like already, yeah, you’re hosed.

Here’s the documentation on ButtonBorderShape. Well, that’s certainly useless to a new person. “A shape that is used to draw a button’s border.” Thanks Chad. Does ButtonRole list all the options for ButtonRole? No, of course not, what could possibly be the value in that? At least EditButton has a screenshot. Someone must have snuck that in.

Over and over, and mind you, this is just for a *button*, Apple’s dev docs are clearly aimed at experienced developers. Oh they have a “Learning SwiftUI section”, but again, who is it aimed at? It takes about ten seconds to realize that “New devs” are not the target of any Apple Docs. Seriously, this?

The MyApp structure conforms to the App protocol, and provides the content of the app and its behavior.

is not something aimed at beginners. Note: I was trained in how to write documentation for doing maintenance on aircraft for people where the sole qualification was “can read english at a 9th-grade level”, I am very familiar with writing documentation for new people.

Now, let’s take a look at the section for a WPF Button on Microsoft’s site: That is a short overview page with an actual screenshot and an explanation of what a button does. Okay, good. Then there’s a link to another Button page. What’s on that? Oh my, everything. No really, everything. Do you need to know how Button fits into WPF overall? It’s explicitly there. Do you want sample code for Hover, Click, and Release in both XAML and C#? Explicitly there. Could use more screenshots, but still. Constructors? Explicitly there, and there’s one, Button().

Fields? There. Properties? Oh my god, all of them. Methods? A huge list with basic explanations and links. There’s even an OnClick() method, what a weird name! An Event listing! If I…click…on the link to the Click event, there’s sample code, and a talk about how a button can be clicked with various things that aren’t mouse buttons, and even what other events can happen with Click and how they’re handled.

There’s a control gallery sample project I can download from GitHub, there’s a tutorial on creating a UI for Windows 10 apps that goes into great detail about what you’re seeing. It explains the obsession with Grid in WPF. Like the first lesson spends a LOT of time on getting you to understand the basic layout of a WPF or UWP app.

Is it easier or better than SwiftUI? That’s a useless question in this context. What is clear is that Microsoft’s Developer Support team is willing to spend a lot of time and effort on helping truly new folks become functional Windows Devs, time and effort that Apple has chosen not to spend. Probably because of some bullshitery about “We’re so intuitive you don’t need training” and “real devs don’t need good docs, just header files.”

I don’t know that for sure about Apple, but that’s damned sure how it feels and I can tell you that as a person who knows less about C# and WPF than I do about SwiftUI, I was able to get a functional app done in WPF and C# far faster than I ever have with SwiftUI (given I’ve never been able to complete a SwiftUI app and I have been able to complete a C# WPF app), and a lot of that was due to Microsoft actually giving a shit about new devs.

That can’t possibly bite Apple in the ass ever.