Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

On Apple's Piss-Poor Documentation

caseyliss.com

Post reply on HN
Print view View original

291–300 of 348 posts

Re: On Apple's Piss-Poor Documentation

#291

Post by teh_klev »

sirmarksalot wrote: post #229
jjkaczor wrote: post #175

Earlier quoted context omitted.

For all the crap that Apple, Java and other open-source people have piled on Microsoft over the years, their developer documentation has always been very good. Yes, there are rough-edges. Back in the day, when Sun was still in-charge of Java, I had my 1-person consulting company partner with Sun and become an official "Certified Java" organization... Great, I thought - now I can get some better documentation... Sure,…

I wouldn't say it's always been very good. How well do you remember MSDN? In the mid-2000s, Microsoft documentation lived on three or four separate sites, and I don't remember the names of all of them. The two that spring immediately to mind are MSDN and TechNet. MSDN had the infuriating issue of broken links. You'd be deep-diving on an issue, find a link to an article that looked like it might perfectly address your…

> It got so bad that a VP ended up making a pronouncement, declaring a war on broken links.

Probably Scott Guthrie initiated that. As some nobody I once emailed him directly because I'd discovered a bug in some framework thing with a reproducible example. He actually replied and cc'd in the relevant people at MS and after a short while there was a workaround and a fix and a KB article or something (it's so long ago I barely remember). Impressed? absolutely. MS still have some pretty good and accessible folks, and I'm a huge fan of Scott Hanselman who's a great brand ambassador for DevDiv (and not beyond a few self-deprecating MS jokes about the company's past).

Re: On Apple's Piss-Poor Documentation

#292

Post by jfim »

mariodiana wrote: post #125

I swear to the gods of Cupertino I am not trying to start a flame war, but -- Apple fanboy though I am -- I recently started taking a look at Flutter and was absolutely floored by the difference in the state of documentation between the two. Leave aside all talk of the viability of cross-platform development. That's not what I'm talking about. I'm just talking about the developer experience of working with the docume…

> We lament that Apple seems to hate its developers.

The joke back then (well over fifteen years ago, pre-iPhone) was that Apple is very user friendly, but that developers aren't users.

It's interesting to see that that hasn't changed since then though, you'd think that with all the iPhone money they would've invested a bit of it in developer documentation.

Out of curiosity, how's XCode these days? Back then it was a rather scrappy team, but it still beat Metrowerks' CodeWarrior.

Re: On Apple's Piss-Poor Documentation

#293

Post by 1MoreThing »

gbear0 wrote: post #152
kaycebasques wrote: post #16

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…

I'll admit that I'm pretty bad at formal documentation myself, but I've been wanting to improve that lately. So as a technical writer do you have any suggestions/links to material for learning the trade or even some sort of formal training courses for professional development that I can pass to my employer?

https://developers.google.com/tech-writing

Re: On Apple's Piss-Poor Documentation

#294

Post by wlesieutre »

uryga wrote: post #276
wlesieutre wrote: post #213

Earlier quoted context omitted.

On the SwiftUI side, you might go digging in these docs for Previews, which are one of its biggest selling points: https://developer.apple.com/documentation/swiftui/previews Take 30 seconds to read through that and the linked pages (that's all the time it will take) and see if you could figure out how to use a PreviewDevice to make your preview show a particular device. It will tell you all the ways to initialize a P…

found something! kinda: https://developer.apple.com/documentation/swiftui/previewpro... an example for `PreviewProvider#previews` uses `.previewDevice("iPhone X")`, and i'm guessing that that string gets turned into a `PreviewDevice` via one of those `fromBlahLiteral` methods it implements? my guess is that `PreviewDevice` is some kind of opaque handle thingy (which is why it has no visible members/methods) but that.…

Good find! For some reason buried two levels deep from the Previews page. I believe you're right that it's silently building a PreviewDevice from the string. You can make the PreviewDevice explicit (as shown in the Hacking with Swift code sample), but nice tidbit that you don't have to.

Re: On Apple's Piss-Poor Documentation

#295

Post by 1MoreThing »

imtringued wrote: post #212

I think this old HN discussion is relevant because it shows that documentation is multifaceted and just one approach doesn't cover everything. https://news.ycombinator.com/item?id=21289832 I have often seen people complain about auto generated documentation being worse than useless when that is not the case. It's not that the documentation is poor, it's that there is a complete lack of the other 3 kinds of documentat…

Big agree, although I think in this case even the auto-generated stuff being talked about is awful.

Re: On Apple's Piss-Poor Documentation

#296

Post by jtdev »

merb wrote: post #194
gumby wrote: post #76

It's really a shame that a scrappy little company like Apple can't afford the resources to produce documentation, even if not for their own apps at least for the developers who write apps that cause their users to buy the hardware. Maybe when they can get themselves established in the market they'll have enough financial resources to invest in this critical area. === I never liked Ballmer, and really never liked the…

> I never liked Ballmer, and really never liked the win APIs actually WinRT is really good. unfortunatly they are barely widespread and probably are not that much used. C# api docs: https://docs.microsoft.com/en-us/uwp/api/?view=winrt-19041

I was shocked as a developer who’s worked with numerous languages and framework, e.g. Python, C#, JavaScript, Java, Go, etc. to look at Apple’s docs... such a mess.

Re: On Apple's Piss-Poor Documentation

#297

Post by mariodiana »

jfim wrote: post #292
mariodiana wrote: post #125

I swear to the gods of Cupertino I am not trying to start a flame war, but -- Apple fanboy though I am -- I recently started taking a look at Flutter and was absolutely floored by the difference in the state of documentation between the two. Leave aside all talk of the viability of cross-platform development. That's not what I'm talking about. I'm just talking about the developer experience of working with the docume…

> We lament that Apple seems to hate its developers. The joke back then (well over fifteen years ago, pre-iPhone) was that Apple is very user friendly, but that developers aren't users. It's interesting to see that that hasn't changed since then though, you'd think that with all the iPhone money they would've invested a bit of it in developer documentation. Out of curiosity, how's XCode these days? Back then it was a…

Well, I like Xcode. But Apple keeps making changes with every version, and some of those changes seem to be for no good reason. You get a kind of muscle memory after a while, from using your IDE. When a button is moved or removed, or a menu is changed, it adds friction to your day.

Also, I got bit with this thing they did for the new ARM chips in the Macs. Our script to build a fat binary (device and simulator) for a in-house framework broke, and we couldn't add the simulator anymore. That took a lot of tracking down to fix. It's constant aggravation like that that wears on a person. Last year, we had the 3rd-party mapping software we use break, because -- as best as I can tell -- Apple changed the implementation for drawing. That was a pain in the ass to track down, too.

I wasn't kidding when I wrote that I was a fanboy. But the other day I was thinking of Steve Ballmer, years ago, running around on stage like a sweaty lunatic -- "Developers, developers, developers!" I mocked him then. Now I'm sorry I did.

Re: On Apple's Piss-Poor Documentation

#298

Post by zaptheimpaler »

Fradow wrote: post #35
psahgal wrote: post #7

Has anyone else noticed that Apple has been slowly moving away from the long-form guides that were helpful at explaining core concepts? I remember once seeing a comprehensive guide on code signing, but over the years it appears to have been scrubbed from their documentation resources. In its place is a much less helpful (but prettier-looking) guide. In comparison, I've noticed Android has FANTASTIC developer document…

Android HAD fantastic documentation, just like Apple had 7/10 years ago. It might not be overly apparent just yet to everyone, but Android documentation is slowly following the same path as Apple documentation, where the experience is slowly degrading, but since it was so good a few years ago, that degradation didn't creep everywhere just yet. My coworker and me are already starting to feel the pain on various core A…

I'm seeing notifications as a feature fail on my android phone too. Apparently there is simply no reliable way to get a notification at a particular time (e.g from a todo app) anymore. ON A PHONE. THE THING DESIGNED TO BEEP/RING/NOTIFY YOU OF THINGS.

Because of all the junk they've added re: battery optimization, "Adaptive AI" notifications. Even after disabling much of that, it takes a 3rd party app to get notifications reliably.

Re: On Apple's Piss-Poor Documentation

#299

Post by [deleted] »

plorkyeran wrote: post #119
wlesieutre wrote: post #6

Earlier quoted context omitted.

I will say that the WWDC sessions are well presented, and are a good place to start. But you can't use a video for quick reference, and you might be missing context from knowing how it worked the previous year to understand what the new enhancements are. Expect to dig into 2019 videos too. SwiftUI being new at least has the benefit that its sessions can't be any more outdated than that (yet). At most you're reconcili…

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.

[deleted]

Re: On Apple's Piss-Poor Documentation

#300

Post by andrewmcwatters »

gumby wrote: post #169
delfinom wrote: post #138

Earlier quoted context omitted.

Apple at this begrudgingly allows developers on their platform as they slowly make their own apps to capture all the recurring subscription revenue as the logical endgame of its walled garden.

This is a common, lazy argument. Apple's bundled apps are typically MVPs rather than best of breed. For me an MVP is perfectly fine for my photos and video editing while, say, for calendar and address book I use third party apps. I doubt anyone would claim that Pages or Numbers are any sort of competition for flagship apps like Word or Excel, while at the same time they don't even break new ground like google docs di…

Yeah, and if you had the balls to make something you thought people would like, you sure as hell wouldn't call it a common, lazy argument, because you'd do everything you could—which is very little—to protect yourself from being cannibalized in the software industry.
Post reply on HN