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

161–170 of 348 posts

Re: On Apple's Piss-Poor Documentation

#161

Post by an_opabinia »

njhaveri wrote: post #85
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?

I also really dislike that WWDC videos are now the de-facto documentation. It must be a lot of work to put them together – I wish they'd just write a doc instead. Would be way faster to read, search, etc. and could probably go into much greater depth.

Yeah but on the other hand, I'm sure they look at the vibrant 3rd party tutorial content pipeline as evidence that they're doing the right thing.

Re: On Apple's Piss-Poor Documentation

#162

Post by kazinator »

You need documentation not just to get your happy case working (how do I call this?), but to know things like:

1. Know whether a good behavior you're getting is a fluke, or required.

2. If something stops working with a new release of the API middleware, is it due to their bug, or because you misused it?

3. What limitations of the API will leak through to your program? What input ranges to watch out for?

4. What unexpected situations could occur that must be handled? These won't happen if you get the happy case working, or not all of them.

Re: On Apple's Piss-Poor Documentation

#163

Post by egsmi »

justinclift wrote: post #106
egsmi wrote: post #62

Earlier quoted context omitted.

There are good reasons to hide the implementation details in documentation. The primary being it’s easier to keep the documentation up to date, our primary topic here. Many languages even publish class interfaces but not necessarily implementation details. That said, a couple of example code snippets on using the interface wouldn’t hurt.

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

Re: On Apple's Piss-Poor Documentation

#164

Post by laichzeit0 »

captn3m0 wrote: post #144
Zelphyr wrote: post #103

Marco is right about PHP's documentation. I've felt for a long time that the quality documentation PHP provided played a major role in the language's success.

PHP's documentation is amazingly well done. It goes above and beyond almost everything else.

PostgreSQL’s documentation is also amazingly well done.

There’s also HighCharts. But not the documentation, rather the fact that I almost never felt like I needed any. The API was just so well done that you didn’t need any. That was my experience anyway.

Re: On Apple's Piss-Poor Documentation

#166

Post by tidbits »

SilasX wrote: post #142
Ronsenshi wrote: post #107

Earlier quoted context omitted.

Already a thing: https://apps.apple.com/us/app/a-companion-for-swiftui/id1485... No affiliation. It's sad and a bit pathetic that trillion dollar company can't hire even one person to work on public documentation.

Reminds me -- it used to be that I could plug my Macbook air into a monitor and arrange my windows, and it would return them to that position whenever I'd disconnect and come back. That feature vanished as of ~2018 and you have to buy some app to get it back.

My Macbook pro still does this. Granted, it's a little wonky. If you alter the window in any way while disconnected then it might not return to the original location. It also doesn't preserve any new desktop environments created on the external display.

Re: On Apple's Piss-Poor Documentation

#167

Post by qppo »

fivre wrote: post #61
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…

> technical writing is almost always understaffed > it's really hard to show a causal link between the docs we create and developer success Amen to that. IMO good documentation is incredibly valuable, but not in a way that aligns with business priorities. At my current job, we hear, repeatedly, that our documentation is poor, and that we need to improve it. Execs echo this sentiment, but the status quo doesn't budge.…

> the writers are all generalists, covering every product from top to bottom. In practice, this means that engineers are asked to draft the bulk of documentation, and the writers scramble to at least copy-edit it.

This seems like an organizational/staffing mistake. In other engineering orgs you'd see these roles filled by applications engineers, who dogfood while evangelizing the product and writing its technical documentation. Ambiguity or questions are handled by conversations with the engineers that built it.

Re: On Apple's Piss-Poor Documentation

#168

Post by leptons »

heavyset_go wrote: post #100
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…

Apple figures developers will still pay them $99/year even if they provide them with poor documentation, and unfortunately, it looks like they're right.

Microsoft: Developers! Developers! Developers!

Apple: Fuck off Developers!

Re: On Apple's Piss-Poor Documentation

#169

Post by gumby »

delfinom wrote: post #138
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…

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 did (yes, I know it wasn't the first either).

And perhaps Apple will get its act together on its subscription services but so far they aren't world beaters either, and never have been (going back at least as far as eWorld in the 1990s).

Re: On Apple's Piss-Poor Documentation

#170

Post by Apes »

ListenLinda wrote: post #112

I'd like to point out this phenomenon is not limited to their APIs. The docs for sys admins are poor as well.

"Poor" implies that it exists at all. For sys admins, most MacOS components are completely undocumented, or are documented with sparse copies of BSD documents from 20+ years ago.
Post reply on HN