On Apple's Piss-Poor Documentation • Hacker News Board

Re: On Apple's Piss-Poor Documentation

#181

Post by wizzwizz4 » Tue, Nov 10, 2020, 7:17 PM UTC

pak9rabid wrote: post #146

pornel wrote: post #47

Earlier quoted context omitted.

I hate that WWDC videos have essentially replaced docs. Videos have to be shallow, and code on slides has to be short. This medium is fine to sell an idea, and to give a high-level overview of how it works, but there's no way to include as much information as written documentation would. Here's a TED talk on Thorium reactors. Why aren't you running them yet?

For all the hate it gets, I think the way PHP does their documentation is ideal. Easy to search for what you need, it recommends other, similar classes/functions, gives a good description of the inputs and what something is expected to return. Then, in addition to that, there's the user-supplied examples and commentary to help further clarify things. I really like the model they went with.

I concur. PHP is a horrible language, but I don't hate working in it. The documentation is the reason.

Re: On Apple's Piss-Poor Documentation

#182

Post by dragonwriter » Tue, Nov 10, 2020, 7:20 PM UTC

throwaways885 wrote: post #154

dragonwriter wrote: post #143

Earlier quoted context omitted.

> The MSDN documentation has always been freely available No, it hasn't. It was originally available exclusively to subscribers, and only on CD. MSDN started before the web existed. Eventually , the documentation became free on the web.

That's a bit unfair. The web is what made it easy to publish at no cost, CD's still had mail and print costs associated so it made sense to send documentation with the software packages it... documented.

What's unfair? It's an accurate actual description with no value judgement.

You seem to be arguing against a negative value judgement which I did not make, or even suggest.

Re: On Apple's Piss-Poor Documentation

#183

Post by bsenftner » Tue, Nov 10, 2020, 7:21 PM UTC

ChrisMarshallNY wrote: post #23

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…

I once owned every copy, of every generation of "Inside Macintosh." I agree about the Android docs. However, in defense of companies that don't like to have too much documentation around, I can tell you, from personal experience, that writing developer docs is hard , as is doing developer support. Keeping them up to date is also a challenge. I call it "concrete galoshes": https://littlegreenviper.com/miscellany/concr…

I was a Mac beta tester back in '83, and still have a copy of the pre-release "Inside Macintosh" mimeographed the day after the original programmers wrote their drafts, filled with penciled in corrections and in some places pages of hand corrected notes. Reviewing a formal copy after edition 2 or 3, I was surprised to see a reduction in information quality and some of the key information from the penciled in notes completely missing.

Re: On Apple's Piss-Poor Documentation

#184

Post by SkyPuncher » Tue, Nov 10, 2020, 7:21 PM UTC

wlesieutre wrote: post #2

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…

I built a SwiftApp a few years ago. I absolutely loved working with Swift, but I could not stand the documentation.

Apple was so happy to push breaking changes (without good documentation), that it made it very difficult to work with.

Re: On Apple's Piss-Poor Documentation

#185

Post by psahgal » Tue, Nov 10, 2020, 7:25 PM UTC

intricatedetail wrote: post #126

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 wonder if this is on purpose and that some companies receive good documentation so that competition is kept at bay. Does Google offer some sort of training packages for Android or you can get a loan dev that knows all the quirks? I've seen this with other companies where documentation is poor on purpose so they can make extra money from training.

I don't think Google does consulting or specialized training like this for Android.

For Google Cloud Platform, they partner with other companies (like the one I work for) to help with GCP setup. This partner program was started in the last few years, so I don't think they were doing this for Android back when Android development was new.

Also, the company I work for spent a lot of time building Android apps for Fortune 500 companies, so I feel like I would have heard about it. Our clients would have benefitted from having Googlers build Android apps and train people!

Re: On Apple's Piss-Poor Documentation

#186

Post by zentiggr » Tue, Nov 10, 2020, 7:27 PM UTC

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…

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 just things users want to do so let's have an app only as needed to retain users, ish.

Really schizoid from my point of view.

Re: On Apple's Piss-Poor Documentation

#187

Post by _hao » Tue, Nov 10, 2020, 7:33 PM UTC

psahgal wrote: post #45

fouc wrote: post #40

How about AWS documentation?

AWS's horrible documentation and user experience is the primary reason I prefer using Google Cloud Platform instead. :-)

From my interaction with GCP docs I think it's way behind both AWS and Azure :shrug:

Re: On Apple's Piss-Poor Documentation

#188

Post by andi999 » Tue, Nov 10, 2020, 7:34 PM UTC

grimjack00 wrote: post #120

lostcolony wrote: post #86

Earlier quoted context omitted.

I've run into this more often than I can count with Java based things. "Just look at the Javadocs!" You...you mean the auto-generated API descriptors that have exactly zero usage information on them, and expect me to figure out how to piece things together just by type signature? That...that isn't how documentation works.

You mean you can't figure things out from "public Session getSession(String, String, String, String, String)"?

We tried to buy some mechanical equipment which can be steered by a computer API. I asked for the doc beforehand. Got something like your example (10 pages of C header). I asked any better docs? Answer:'a real programmer would know how to use this' - well somehow they didnt manage to sell the device to us. Later they managed to email the comprehensive docs (which existed!), but we alread spent a much larger amount (without regrets) to the competition.

Re: On Apple's Piss-Poor Documentation

#189

Post by ARandumGuy » Tue, Nov 10, 2020, 7:35 PM UTC

I looked at the example the article links to, and it's worse than it portrays. Not only is there no information on the requestAuthorization page, but the enum type used, PHAccessLevel, also contains no documentation! Apple, how hard is it to write the different values for an enum?!?

Re: On Apple's Piss-Poor Documentation

#190

Post by samatman » Tue, Nov 10, 2020, 7:45 PM UTC

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…

No, but I would staunchly argue that Keynote is better than PowerPoint for making and giving presentations.

Apple cares about presentations, and is lukewarm at best about making documents and running spreadsheets. It shows.