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

301–310 of 348 posts

Re: On Apple's Piss-Poor Documentation

#301

Post by Dahoon »

zaptheimpaler wrote: post #298
Fradow wrote: post #35

Earlier quoted context omitted.

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 notificat…

Sure there are. I get one every day from my alarm clock 5 minutes before it starts yelling at me.

Re: On Apple's Piss-Poor Documentation

#302

Post by mikepasz »

yoz-y wrote: post #222
delfinom wrote: post #140

Earlier quoted context omitted.

Apple slowly wants to pump out their own apps that do everything to maximize their recurring subscription revenue. Why settle for 30% when you can take 100%.

There is no evidence of them doing that. Pretty much the contrary is happening.

At the very least, there is evidence of Jobs' sentiment early on to prevent 3rd party apps on Apple's platform https://www.cultofmac.com/125180/steve-jobs-was-originally-d...

Re: On Apple's Piss-Poor Documentation

#303

Post by gentleman11 »

ffhhj wrote: post #216
gentleman11 wrote: post #116

Earlier quoted context omitted.

Unreal engine is like that, except with fewer third party tutorials. It’s getting better but the c++ docs are almost as bad as having nothing. Some of them only have comments like “maybe refactor this” as a description, and the community wiki was taken down recently too

Years ago I worked on the documentation for one of those big game engines. Previously as a "user" I suffered a lot with their physics system, and there was a big gap about its performance and best practices. After a long research in the source code and emails back and forth in the company I was able to fill those holes. My motivation came completely from within me, because absolutely no one in the company seemed inte…

Your work is deeply appreciated

Re: On Apple's Piss-Poor Documentation

#304

Post by crowbahr »

jtdev wrote: post #296
merb wrote: post #194

Earlier quoted context omitted.

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

Leaving iOS dev for Android Dev was the best choice I ever made. iOS dev was consistently miserable.

Re: On Apple's Piss-Poor Documentation

#305

Post by rdn »

EdwardDiego wrote: post #259
rocho wrote: post #215

Earlier quoted context omitted.

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

At least you can read the code, Apple's libs are closed source. You have to resort to reverse engineering techniques to fill in the documentation gaps.

Re: On Apple's Piss-Poor Documentation

#306

Post by tasogare »

markdoubleyou wrote: post #253
ethbr0 wrote: post #158

Earlier quoted context omitted.

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 th…

I use C# daily and most of the time the doc is fine. I agree that sometimes dotnet core docs are a bit messy and frustrating, but still quite good and useful.

Re: On Apple's Piss-Poor Documentation

#307

Post by revel »

simonw wrote: post #217

The difference between https://developer.apple.com/documentation/photokit/phphotoli... and its replacement https://developer.apple.com/documentation/photokit/phphotoli... is pretty damning.

This is just so.. amateur. The message this sends to me as a developer is: don't waste your time with this unless you have no choice

Re: On Apple's Piss-Poor Documentation

#308

Post by bhrgunatha »

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…

They also suffered the same problem mentioned in this post.

Documentation pages that showed a method's signature with no explanation of the function or example usage. So many times I'd look something up only to find the method name parroted as a full sentence; and those method names were often obscure to the point of meaninglessness.

Re: On Apple's Piss-Poor Documentation

#309

Post by Polylactic_acid »

hutzlibu wrote: post #177
_qulr wrote: post #64

Earlier quoted context omitted.

The other day someone referenced this post by an Apple engineer: https://developer.apple.com/forums/thread/663858 Why in the world is this a random undiscoverable post in the (terribly designed) developer discussion forums rather than a Technical Note in the documentation? It would have been a TN in the past. In fact that same engineer wrote a number of old Apple TNs. It's clear even to some within Apple that there's…

Current situation is, money is coming in. Stock market still loves apple. So for them it seems fine.

Basically. What are you going to do? Not release your app on apple devices? No, you will do whatever it takes to work it out yourself.

Re: On Apple's Piss-Poor Documentation

#310

Post by dwiash »

psahgal wrote: post #43
Fradow wrote: post #35

Earlier quoted context omitted.

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…

Even 5 years ago, I felt that Apple's documentation was way worse than Android's. I wonder if there is a good way to measure documentation quality...I suspect such measures will require techniques borrowed from user experience research.

Yea, i think that's correct. documentation is just another product, no different than other software. so basically you can start asking with very common user reasearch questions such as: * who would use our documentation? * what would our user need the most from our documentation?
Post reply on HN