Hacker News Reader

Comment by pjmlp | Hacker News Reader

On the old Mac OS, and early OS X day, the documentation was great, I dunno what happened to the documentation team.

Swift on the server is for Apple ecosystem developers, to share code, just like all those reasons to apparently use JavaScript on the server instead of something saner.

View on HN

I found some of that older documentation one day while being beyond frustrated with understanding some underdocumented iOS library APIs and it is incredible. What they have now is a joke in comparison. WWDC as a documentation strategy is terrible for people that learn from text. And it’s just a bad medium to begin with for information transfer. By its nature it’s bad at information density, and is often distracting and filled with fluff.

Yes, some of it survives on the archives, who knows for how long, always save copies of them.

I wonder if it is a generation gap, as many apparently learn coding via videos, however that it is not enough to go deep.

By the way, Microsoft suffers from the same diseas, they reduced their team size, ans unless one is coding since the 16 bit days, there are many things no one will find.

Some of it is gone forever, as they kept replacing their documentation, blogs and video platforms.

Other is still there, but you have to have actually used that in practice, to find out the Win32, or .NET Framework documentation that nowadays only gives the most recent version.

Or even Microsoft Systems Journal articles, as another example.

Google on Android is also a mixed bag, depending on what one is looking for.

My belief is that taking the time to write docs is kinda like an editing process of your thinking. You start to think hard about the reasons you've written an API and how it could be better. And there's a limit to how big you can think about something as a whole so you will naturally try to modularize and layer things. Not just adding things in an adhoc fashion.

I think they threw the towel when they realize the mess they've built. In contrast you have things like RHEL, FreeBSD, etc, where there's a drive to keep things small and neat just to be able to document them.

Articles get removed from Apple's documentation archive seemingly randomly. However, on a good note, there are backups of the entire ADC Leopard Reference Library (available at several places online). That covers that vast majority of all the documentation Apple's ever produced. There's also the Apple II FTP archives, which have older but often less applicable documentation, but are definitely still valuable troves of information.

The story I have heard was that they all got shit canned. They were professional technical writers focused on telling you “why”. These days most of Apples docs are “what”, and a lot of those don’t even tell you anything. Enums without values documented. Class docs that amount to “yep this class exists”.

I remember it being pretty good circa 2012 or so. The API docs generally told me what I needed to know and there were some helpful in-depth technical notes. Did they lose something in the redesign or Swift migration?

It was starting to go downhill even then. They let go a significant number of documentation people for whatever reason.

> JavaScript on the server instead of something saner

JS on the server is actually really fast and well supported. Not really sure what you're driving at here.

It might be fast, doesn't make its WATs go away.

https://blog.kevinchisholm.com/javascript/javascript-wat/

Thankfully we can thank someone with the lifetime experience of designing Turbo Pascal, Delphi, J++, C#, and his team, to have made the experience bearable.

Marketing pushed for features faster than engineering could build them properly to the former standard (quality and documentation).

Ever seen the compiler support tables for ISO managed languages, Web or Khronos standards?

No but I noticed software quality went down when they added emojis

Reply on news.ycombinator.com