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

41–50 of 348 posts

Re: On Apple's Piss-Poor Documentation

#41

Post by OliverJones »

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 (Apple) is unwilling to make the functional commitments implied by good documentation. Once the documentation says "this does that" it's harder to change "this" to do something else.

In the distant past, Apple teamed up with the publisher Addison-Wesley to create and publish high quality documentation. They could certainly do so again, with A-W or O'Reilly or whoever.

But they won't do it as long as they have business reasons not to. They have sufficient control over their marketplace to refuse to do this and get away with it.

Re: On Apple's Piss-Poor Documentation

#42

Post by p_l »

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…

As someone who was in the so called "DevOps" position for years, I'm slowly becoming tired of asking management for "give me a technical writer, even half-time, instead of another dev/ops person" :(

Re: On Apple's Piss-Poor Documentation

#43

Post by psahgal »

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…

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.

Re: On Apple's Piss-Poor Documentation

#44

Post by david-cako »

kevingadd wrote: post #36
david-cako wrote: post #27

Apple seems like they are willing to double down on SwiftUI/UiKit with Catalyst. It's getting less simple for new APIs/features but at least Apple's docs have straightforward hierarchy, even with two separate languages. Duplicate APIs usually get deprecated, like the old ALAssets photo library API. Try building an app in .NET. There are dozens of different breadcrumbs you can follow on the MS docs for varying version…

Is it really an asset to not have documentation for old frameworks or versions? Some people have customers on old hardware and legacy code using old APIs that they might need to integrate with, it's useful to be able to find out how that stuff behaves.

That's the thing, it's all still there, but it's abundantly clear based on the pages and the list of supported OSs/platforms whether you can use it, and what the new API is.

https://developer.apple.com/documentation/assetslibrary

Re: On Apple's Piss-Poor Documentation

#46

Post by lordleft »

A middling language with exceptional documentation can sometimes be more effective than an exceptional language with spotty documentation. The friction of acquiring sufficient context to get up and running with a language is a huge part of any technical task IMO.

Re: On Apple's Piss-Poor Documentation

#47

Post by pornel »

wlesieutre wrote: post #6
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 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 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?

Re: On Apple's Piss-Poor Documentation

#48

Post by dep_b »

Hah the nightmare to get CallKit working. The only thing you could do is take a working example application and step by step wrap your application around it.

Because taking your existing VoIP application and inserting CallKit behavior breaks in so many mysterious and undocumented ways that I really had to tell a client it wasn't going to happen with his existing application within the allocated budget.

Just to get the fancy Apple call screen!

And of course only FaceTime can take video calls straight into video from the lock screen, so you have to explain after it works why nobody can see each other.

Re: On Apple's Piss-Poor Documentation

#49

Post by toopok4k3 »

I don't think Steve would have allowed this to happen. Developers are way too important part of the whole "where the money comes from?" question. He would have noticed the complaints before anyone wrote a blog about it.

iOS docs were great back in 2011.

Re: On Apple's Piss-Poor Documentation

#50

Post by StillBored »

This isn't an apple thing. Its industry wide. Much of the good documentation that exists is stuff that was written 20+ years ago by actual technical writers and is still being maintained.

AKA the windows API/etc documentation, linux man pages, etc.

The vast majority of modern documentation is worthless autogenerated garbage when it exists. It lacks good examples, meaningful overviews and functional diagrams. In many cases its woefully out of date because someone rejiggered an API and didn't bother to even update the inline documentation.

One of the better examples of recent documentation is the core rust docs/books. Even then because the rapid release cycles no one publishes an updated "Learn Rust" book for every release, complete with boxes explaining what has changed since the last release. And god help you if you dig to far into the library ecosystem.

I think this is caused by one single problem. Documentation isn't sexy and no one is paying technical writers to do the grunt work anymore. Opensource is a large part of this problem, but the commercial guys have discovered they can save a few hundred thousand a year by simply not having a documentation team, and it doesn't appear to affect them much. A couple youtube tutorials and they are done.

You can see this in the evolution of software, etc. In the 1970's you got large paper manuals which covered every technical aspect of the machine/software. The users were expected to use their brains. Then in the 1980's it all transitioned to "user documentation" which was more focused on manuals that explain how to use the product, by removing the how it works part. Then in the 1990's it started moving to digital copies on disk, and the product came with a 3-4 page manual explaining how to bootstrap enough to read the rest of the docs. In the 2000's it all moved online and became more "marketing" than users guides. In the 2010's they stopped even that. Now you get a phone/software/computer your lucky to even get a piece of paper that tells you how to turn it on, charge it, or install it. Even ms doesn't publish a complete guide to all the magic swipes and keystrokes that are supported by their new shell.

Post reply on HN