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

331–340 of 348 posts

Re: On Apple's Piss-Poor Documentation

#331

Post by arthurcolle »

laichzeit0 wrote: post #164
captn3m0 wrote: post #144

Earlier quoted context omitted.

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.

I wanted to print out the Postgres documentation to have a physical copy and then my jaw dropped, realizing I would need to print out 7 double sided 50 page booklets if I wanted to do this! 300

https://www.postgresql.org/files/documentation/pdf/13/postgr...

Re: On Apple's Piss-Poor Documentation

#332

Post by Austin_Conlon »

lostgame wrote: post #113

I've been working on a very simple (but extremely useful) WatchOS project I'd like to keep under wraps for the time being, as I think it could certainly sell. Apple's WatchOS documentation, however; is sparse at best, barely there at worst. It's been a problem with various Apple documentation for years.

Out of curiosity, are you talking about WatchKit or SwiftUI?

Re: On Apple's Piss-Poor Documentation

#333

Post by on_and_off »

saagarjha wrote: post #285
on_and_off wrote: post #96

Earlier quoted context omitted.

stupid question : but is there any specific reason why swiftui is not open source ? I am working with jetpack compose these days and it is both open source and documented. I am not sure how I would work with it without that, it is quite a big departure from the legacy ui api.

Probably because it’s a competitive advantage for Apple to keep to themselves.

I wonder how much of an advantage it is practice ? It is one such toolkit among others, like React or Compose. It is different from making the whole OS open source.

I guess that since the benefit would be to make third party devs job easier, the incentive is not that great for apple .. devs will write mobile apps even if they have to write them in assembly.

Re: On Apple's Piss-Poor Documentation

#334

Post by aszlig »

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.

That's certainly true for the standard library and the documentation on the language itself. However for the internals, this wasn't always the case and it looked more like this:

http://web.archive.org/web/20060626083819/http://www.php.net...

Re: On Apple's Piss-Poor Documentation

#335

Post by bsenftner »

ChrisMarshallNY wrote: post #236
bsenftner wrote: post #183

Earlier quoted context omitted.

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

That is a cool story. I got my first Mac in '86 (a Mac Plus). My first copy of Inside Macintosh was the hardcover. I think it was two volumes, back then.

The original Inside Mac was 3 volumes, after their initial printing of the "phone book edition" - all three volumes in one thick soft spine binder. I really need to take the time to scan my copy and put it online. It's got ballpoint pen corrections from the Apple Engineers telling the beta testers various fixes.

Re: On Apple's Piss-Poor Documentation

#336

Post by zentiggr »

gumby wrote: post #193
zentiggr wrote: post #186

Earlier quoted context omitted.

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

I am an iOS and macOS developer and user and it doesn't look that way to me at all. (FWIW I use their hardware because IMHO it sucks less than the alternatives; I'm no special fan). Actually this part I agree with 100%: > 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. And I assume this hardware focus is…

I appreciate that closer perspective - I've never been even moderately involved so I expect I only see the noisy things.

The earlier machines I've worked on always did come across as well designed and at least generally well thought through.

Re: On Apple's Piss-Poor Documentation

#337

Post by jjkaczor »

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…

Heh... well, I am old enough to remember the offline MSDN - which was great, and the rough transition to online - which got better, eventually... (and the rise of StackOverflow makes more sense in that context) but then at the beginning of the "cloud-era", IMO, it got worse again - to the point that I was constantly complaining about blog articles by MSFT employee's that really should have been folded into the actual documentation/KB instead...

It's a hard sell to tell an IT decision-maker in a different team/group that you need to configure things "just so" (think TechNet versus MSDN for configuration/operational articles) when all you have to point them too is a non-official blog post...

(Don't even get me started about the quality/out-of-date materials for things like Dynamics 365...)

Re: On Apple's Piss-Poor Documentation

#338

Post by jyounker »

Spivak wrote: post #159
piva00 wrote: post #129

Earlier quoted context omitted.

A trillion dollar company should be able to hire some technical writers to embed into teams and write documentation as part of the process. It's just a lack of care when you have that amount of money.

It's not really the size of the company. Anyone qualified to write good documentation can make better money, work on more interesting things, and advance their career by actually working on the code. Without a culture that rewards and values the work it doesn't get done.

This. Developers aren't getting credited or promoted for writing documentation, or assisting in the process.

Re: On Apple's Piss-Poor Documentation

#340

Post by dorado3 »

Every June we hear dozens of statements like "We're so excited to see what you do with X. It's so new and amazing." And yet, they barely lift a finger to help developers understand how to use X properly. SwiftUI is a perfect example.

Their developer forums are apparently a place to talk to yourself.

Something is deeply wrong with them and I can't tell if it is merely a case of extreme oblivious arrogance, or if they are self sabotaging, perhaps unconsciously.

Post reply on HN