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

341–348 of 348 posts

Re: On Apple's Piss-Poor Documentation

#341

Post by OliverJones »

_qulr wrote: post #59
OliverJones wrote: post #41

Here's a contrarian view of this (deplorable) situation, from someone who developed for Microsoft platforms for years. The low quality of the documentation has two reasons: * Protectionism: The poor documentation defends expert third party developers against competition from new entrants. It ensures a shortage of competent developers and so enhances the revenue of established experts. * Low commitment: The publisher…

> The poor documentation defends expert third party developers against competition from new entrants. It ensures a shortage of competent developers and so enhances the revenue of established experts. Why in the world would Apple want to ensure a shortage of competent developers — for apps on Apple's platforms! — or protect third party experts?

Why do they want dev skills to go at a premium price? For one thing, they do not have any shortage of apps coming in to their app store. They're no longer in the business of begging people to deploy apps. Instead, they're in the business of vetting the apps people submit.

Raising barriers to entry for new developers is a cost-cutting measure for them. And fewer apps on the store, even at the margins, is a revenue enhancer for incumbent app developers.

This may or may not be an explicit factor in their decision making. But it surely contributes to their lack of focus on docs: better docs will improve their profitability not at all.

Re: On Apple's Piss-Poor Documentation

#342

Post by benmathes »

descriptively: Apple has enough market clout so that it (implicitly) thinks developers will pay the time cost to overcome the lack of documentation and save apple the time it would take to write the documentation. The lever isn't good/bad docs, it's the market dominance apple has in controlling access to high-spend customers.

Similarly, MS was notoriously hard to dev on during MS's period of market dominance. It's a lot more dev-friendly now because it doesn't dominate as much anymore.

Re: On Apple's Piss-Poor Documentation

#343

Post by justinclift »

egsmi wrote: post #163
justinclift wrote: post #106

Earlier quoted context omitted.

> The primary being it’s easier to keep the documentation up to date ... That's NOT a "good" reason in any sense. That's a terrible reason, which no-one in a team leader or above position should ever sign off on.

We're going to have to agree to disagree on this one. But let me give you all an example. Wolfram Documentation on Mathematica is excellent in my humble opinion. Here is a function I use very often, convolve. https://reference.wolfram.com/language/ref/Convolve.html Notice how the interface is very well described, there are examples on how to use it, but there are no implementation details.

Your reference example includes lots of details, examples of usage including source, explanation of options, etc. :)

That's not an "easier to keep documentation up to date" type of thing ;), but is definitely an example of good documentation.

Unlike the Apple approach mentioned above. :( :( :(

Re: On Apple's Piss-Poor Documentation

#344

Post by int_19h »

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…

In late-90s to mid-00, if you did any serious Win32 or .NET development, you had the MSDN Library installed locally - it had its own help browser, with integrated search and index. The latter was especially useful, since it contained all structs, classes, interfaces, functions etc, across all platforms for which docs were installed.

Anything that was available online, official or not, was inferior to that. I'm not sure if it was deliberate, but it significantly hampered the utility of pirated copies of Visual Studio - since MSDN docs would require a lot more CDs than the software, most warez releases stripped them out. And in the developing world, where such pirated software is readily available on physical CDs sold by street vendors, they would usually be priced per CD regardless of what's on it - so a complete VS+MSDN bundle would be a lot more expensive, and thus in relatively low demand, and not widely sold.

Re: On Apple's Piss-Poor Documentation

#345

Post by int_19h »

ethbr0 wrote: post #204
wlesieutre wrote: post #192

Earlier quoted context omitted.

There's an old saying at Microsoft: developers, developers, developers, developers, developers, developers, developers, developers

It's mocked, but the underlying observation is astute. In the personal computing world, first parties can't build enough user software. Furthermore, software availability and reliability lag third party developer and development ecosystem health. A bad experience doesn't hurt the platform today , it hurts the platform in 1+ years. And perhaps even worse, steps to address it take effect over a 1+ year timeframe as wel…

If you recall, back when the first iPhone came out, the idea was that Apple itself would be the only provider of first-class software for it, and everything else was relegated to web apps.

It didn't work out for them back then, and so we got native apps and the store. But I can't help but think that Apple still sees it as a sort of compromise of their ideal vision of what the platform should really be like, and thus dev ecosystem evolution is mostly on the backburner. Just look at how long it took for Swift to appear, despite Obj-C being really dated by that time.

Re: On Apple's Piss-Poor Documentation

#346

Post by int_19h »

auggierose wrote: post #265
alexashka wrote: post #254

Earlier quoted context omitted.

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

I had the pleasure to attend a talk given by Joe Armstrong. For some reason he was always looking over to Phil Wadler, apparently looking for approving nods, but there were none to be found :-) I hear what you are saying. I also find it unfortunate that something simple like UI is so fragmented. But then again, maybe UI is not so simple after all. The current paradigm that SwiftUI copies and evolves is that of React,…

Is it progress, though? If the React paradigm is so much better, you'd expect some kind of UX renaissance stemming from its adoption. Instead, we're still struggling with Electron-based apps that are "prettier" but less productive than what we had 20 years ago, back when they were written in UI frameworks that barely even had any data binding at all.

Re: On Apple's Piss-Poor Documentation

#348

Post by EdwardDiego »

rdn wrote: post #305
EdwardDiego wrote: post #259

Earlier quoted context omitted.

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.

That's a very good point. Reminds me of the bad old days of .NET (pre 2.0) where the documentation was a bit shit, and you ended up relying on Reflector to figure out wtf was going on.
Post reply on HN