Lack of Guides and API descriptions in Documentation

Question

Created Jul ’19

Replies 4

Boosts 1

Views 1.7k

Participants 3

I feel sorry for developers to the Apple platforms these days. They will never know how good Apple's Developer documentation once was.

A decade ago, it was truly a pleasure to read about how to build things with Apple's OSes. There were well written guides on each subsystem that told the developer how the subsystem worked and how to solve common problems in code using the subsystem. And the reference documentation actually documented every API. None of this "no overview available" crap when you click on an api.

These days developers are stuck searching StackOverflow, wasting an hour watching a WWDC video in the hopes that it might talk about the api that you need (thankfully they are at least searchable now, so you can at least quickly find out that they almost never contain the answer that you are looking for), or asking on dev forums in the hopes that someone might answer in a reasonable time.

These are all fine _additional_ aids in development, but good guides and complete references are a must. And it isn't like Apple doesn't have the cash to hire the writers that they need.

Also, who had the bright idea of making the developer click through the details of each api to figure out whether the api is available on a given OS or not. How about giving me a filter that lets me select the OS that I'm actually working in?

Ah well...

Done ranting...

Jason

Boost

Answer 1

KMT OP

Jul ’19

Jason:

>bright idea of making the developer click through the details of each api

I suppose you mean supported SDKs missing here...https://developer.apple.com/documentation - it would help to have them listed there, I think.

This decade, Apple has taken more to favoring 'discovery', ala hunt the wumpus. I don't like it any more than you do, but that and moving things around for no reason other than change/for/change's sake seems the routine now. Must be some sort of test, like a hurdle to check motivation and curiosity. That and I guess the best way for new teams to show they're doing something is to rearrange the furniture and unscrew the light bulbs. Weird definition of 'update' if you ask me...more like make work. In any case, it's a disturbing habit on Apple's part. I gave up complaining about it a long time ago.

Feel free to file bugs against the docs using the bug reporter/suggestions link below, adding your report #s to your thread for reference, thanks and good luck.

Ken

0

Answer 2

Claude31 OP

Jul ’19

Yes, Inside Macintosh was a marvellous doc. True to say, API was much simpler.

Clearly now, it is really a nightmare to learn how all things work together.

Fortunately, these forum helped a lot, but I do not find it an excuse…

0

Answer 3

jbobier OP

Jul ’19

Inside Macintosh was amazing! I did an independent study on Macintosh programming in college and read them all from start to finish. (Well, the old ones... I-VI... then they split it out into like 20 different books. Not quite the same, but the writing was still good!)

Jason

0

Answer 4

jbobier OP

Jul ’19

OK, I'm going to make a list of documentation features that we'd like to see. I'm including these to start, but would like other ideas in case there is stuff that I haven't thought of.

1. Bring back the guides documenting how each subsystem works

2. Document every api call

3. Allow filtering of APIs by availability in OS and version

4. Bring back the short summary of the API changes ordered by date (flipping the disclosure triangle here: https://developer.apple.com/library/archive/navigation/ displayed this information before.

Others?

Jason

1