Live data from Hacker News

On Apple's Piss-Poor Documentation

caseyliss.com

251–260 of 348 posts

Re: On Apple's Piss-Poor Documentation

#251

Have you considered using Qt? It compiles and runs native on macOS, the documentation is superb. You just let the Qt people worry about the Cocoa, Quartz etc. interface. As a bonus, it will also run on Windows, Linux, Android, iOS. Qt looks like an "operating system". It isn't really an O/S, it feeds off the underlying O/S, but to the applications programmer, it completely subsumes the O/S. We converted a 500KLOC Win…

Qt is not true Cocoa, even still - IIRC (and I think it was literally somewhere on this forum that I was corrected by a Qt engineer) they use the Cocoa things to handle some drawing code, but it's still their own stuff on top of that (they used to use HITheme & co before they modernized it).

It's why you'll see subtle differences on things like buttons.

Re: On Apple's Piss-Poor Documentation

#252

My other problem with Apple is the lack of PDFs. Apple has a bookstore, I should be able to download the whole of Apple's Developer Documentation on my iPad. I would prefer PDF because I cannot read a screen for hours. Plus, the examples are almost always broken and don't compile. Broken samples and videos are horrible ways to teach anything.

They used to have PDFs linked from the documentation pages. Obviously that went away at some point.

Re: On Apple's Piss-Poor Documentation

#253
post #158
post #129

Earlier quoted context omitted.

A trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.

Just hire Microsoft's people. Not even joking. https://docs.microsoft.com/en-us/dotnet/api/system.string.su...

For Microsoft it depends on when the docs were written.

The MS docs from the late '90s through about 2015 were stellar. For example, look at the Windows Sockets docs[1], which came out of that era. Here you see information architects working at the height of their power: Content is broken up into conceptual ("About Winsock"), task-based ("Using Winsock"), and reference ("Winsock Reference") topics. They were doing this kind of structured documentation before DITA was a thing. It's a pain in the ass to produce content this way, but the results are wonderful.

Then came .NET Core: a fast-moving, community-driven effort, where the philosophy seems to be to get it working and then scribble down some docs later. The result tends to be a huge wall of text with conceptual and sample topics jammed together ([2]), and you're lucky if the API reference gives you anything beyond parameter names.

Azure docs suffer from a different problem. It seems they've tried to apply some kind of rough information architecture, but the quality isn't great. I've looked at the GitHub history of some of the shoddier topics, and they're often written by junior Product Managers who are fresh out of college. I encounter a lot of imprecise, colloquial English describing out-of-date screenshots.

I don't mean to belittle the people who work on .NET Core and Azure. There's a ton of content that needs to be written for these products, and it's a thankless task for the devs & PMs who do the heavy lifting now. I'd really like to see some dedicated technical writers come in and bring the quality back up to their old standards.

[1] https://docs.microsoft.com/en-us/windows/win32/winsock/windo... [2] https://docs.microsoft.com/en-us/aspnet/core/fundamentals/ro...

Re: On Apple's Piss-Poor Documentation

#254

Earlier quoted context omitted.

Ah, we are so lucky to have a framework full of language features that only it uses and an ability to drop down and learn a whole other suite of frameworks that work completely differently to achieve the same task! I've been so lucky to have to learn near a dozen programming languages in the span of less than a decade to write CRUD apps that appear on screens and do the same thing on each platform slightly differentl…

Well, stop writing CRUD apps! That's boring indeed. How about you do some real software?

I am 'doing' real software - I saved up my money writing CRUD and quit as soon as I could afford to.

What I am personally doing in no way negates the fragmentation that is present. SwiftUI is the latest contributor to never-ending CRUD hell and I am merely informing the young and impressionable, that SwiftUI is not your friend - it is your anti-cross-platform, proprietary, closed source devil spawn (being dramatic for fun :)) and if you ever want to start solving real world problems instead of learning the latest framework that does what we did 20 years ago but 5% better this time, you better listen real careful to annoying debby-downers like me, Joe Armstrong (RIP), Rich Hickey etc who got fed up with the corporate matrix and went a different way.

Re: On Apple's Piss-Poor Documentation

#255

I've been a technical writer for ~8 years (3 at a startup, 5 at Gooble). I don't know Apple's situation but here's my guess: > Is the documentation team too small? (Likely.) Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it's safe to say how important it is for job success) yet technical writing is almost always understaffed, no m…

To be honest, was this helpful button is rather vague and I usually ignore it because it doesnt seem to be the right question or rather its a request for feedback I don't know helps me or not.

I advocate for "was this page helpful?" being the standard question across docs sites because ultimately it does reflect the purpose of documentation (to be helpful in one way or another, which usually means helping you complete a task or understand a concept) and because using the same question on all sites enables us to benchmark and compare. I once ran an A/B test on the same page where 50% were prompted "was this page helpful?" and the other 50% were prompted "was this page useful?" and the results were different to a statistically significant degree which suggests that even minor rephrasings skew the results, so we need to all use the same terminology.

> its a request for feedback I don't know helps me or not

Yes I'm aware that readers aren't incentivized to respond which explains why it's rare to get higher than 5% response rate. This situation is a microcosm for documentation's overall problem: we can't find incentives for people to voluntarily and consistently confirm the value we provide and we don't have any other means to prove the causality.

Re: On Apple's Piss-Poor Documentation

#256

Earlier quoted context omitted.

I'm sensing an assumption that Apple needs their in house apps to be best of breed. I'm not an iOS or macOS user, but I've worked on systems over the years. It really seems like they're happy to let someone get popular to identify the niche that needs to be filled, roll an MVP to cover it, and kick out the originators with no real excuses. It's like they're still focused on hardware development and the software is ju…

In the end they want to save on r&d / market research costs. In Ye Olde Times, Apple would go on their own and ask themselves "how can we make an improvement in the lives of our customers?"... the answer were iconic, revolutionary products (iPod, iPhone, earpods) that outright created entire device classes. Now? The only thing in focus is rent extraction - App Store cuts -, recurring revenue and vertical integration.…

> Now? The only thing in focus is rent extraction - App Store cuts -, recurring revenue and vertical integration. Anything not contributing to that gets atrophied (documentation, as mentioned, or Apple Server) or put on life support (essentially the whole rest of the ecosystem, including for all too many years pro-level hardware). Innovation? Why should Apple take the risk and improve their core product with features that won't get used?

well, thats the system we live in; companies are chartered to make profit...

to be honest, im surprised we get even the current level of support and innovation from apple that we do... i think in the long term though, this will only hurt apple, as other alternatives will be more plesant and easy to develop, the only thing keeping apples controlover devs will be its vice-grip on the appstore...

Re: On Apple's Piss-Poor Documentation

#257

Earlier quoted context omitted.

I don't really consider most WWDC videos documentation. They're usually just marketing videos which show off the new features. Even the more in depth videos are rarely more than a shallow introduction.

Unfortunately there's bits of information that are important and only ever appear in the WWDC videos.

There's also a lot of useful information that has only ever appeared in Twitter conversations between Apple developers but I wouldn't call that documentation either.

Re: On Apple's Piss-Poor Documentation

#258

Earlier quoted context omitted.

Already a thing: https://apps.apple.com/us/app/a-companion-for-swiftui/id1485... No affiliation. It's sad and a bit pathetic that trillion dollar company can't hire even one person to work on public documentation.

It’s because engineers don’t want to write documentation, and if you don’t force it this is the result.

wrong! bad engineers don’t want to write documentation

Re: On Apple's Piss-Poor Documentation

#259
post #215

I’ve been picking at SwiftUI recently and run into this myself. You want to know how something works or how to use it, so you go to Apple’s documentation. “Here’s the type signature, have fun!” Thanks. But I was hoping something more than what Xcode’s autocomplete already filled in for me. So instead you end up on 3rd party tutorials (special thanks to John Sundell and Paul Hudson) and always looking at dates on Medi…

> “Here’s the type signature, have fun!” My experience with Go libraries in a nutshell. One of the factors that made me abandon that language for others that for me are much more productive.

Yeah, I've found that quite often in apps/libs written for K8s in Go - wasn't sure if it was a Go cultural thing or a K8s cultural thing.

If you're lucky you're getting an example or two in the README.md. The rest of the time, you're reading code to figure out the intricacies.

Re: On Apple's Piss-Poor Documentation

#260
post #239

Earlier quoted context omitted.

This answer doesn't really work for me. iOS is Apple's bread and butter, and they make good money off those developers. It's in their cynical self-interest to spend the money to have the best documentation in the game, and it would even pay off inside Apple, with better APIs and better resources for their in-house teams to develop against. It seems like a genuine institutional dysfunction. Apple has a culture of secr…

I can also do handwaving culture arguments like apple design in a minimalist fashion, so everything that can be left out will be, including documentation. But I don't like those, I hate to diagnose cultures I only read about. However, apple is a business, and leaving out docs makes business sense and is an easy and straightforward explanation.

They spend a lot of money on things like Swift Playgrounds, though. They have a whole developer outreach and training program: https://developer.apple.com/learn/curriculum/

It's a puzzling omission, given that building App Store revenue is such a priority, and they feed the supply side in a number of other ways. I don't think they're doing it on purpose, they're just bad at it.

Post reply on HN